Flesh out the requirements of subsites

[ang-zeyu]

Subsites work under the philosophy of - "you can create separate sites, then include and use one in another, but the included site should behave as if it was never included" (correct me if i'm wrong)

Currently however, only the following behaviours comply:

• {{baseUrl}} resolves to subsites' root directories
• nunjucks paths resolve from subsites' root directories for subsites' pages (Fix nunjucks path resolving #1263)
• deploy config of subsites is correctly ignored

All other things here don't comply (based on some white box inferencing) (except baseUrl which shouldn't comply): https://markbind.org/userGuide/siteJsonFile.html

• subsites incorrectly share faviconpath
• subsites incorrectly share titlePrefix
• subsites incorrectly share layouts with the root site
• subsites incorrectly share theme configuration with the root site
• subsites incorrectly share page configuration with the root site
• subsites incorrectly share globalOverride
• subsites incorrectly share externalScripts
• subsites incorrectly share ignore config
• subsites incorrectly share plugins and plugin configuration
• subsites incorrectly share headingLevelIndexing

share - meaning subsites' pages should not be able to access the root site's properties / layouts / etc., only it's own. (it should be built as if it was built standalone)

All of this should be able to be easily achieved by creating a Project abstraction of sorts, which holds multiple Sites, although some refactors might have to be made before that.

[damithc]

share - meaning subsites' pages should not be able to access the root site's properties / layouts / etc., only it's own. (it should be built as if it was built standalone)

Keep in mind that the outer site should be able to override things in the sub-site (without modifying it) as that is one of the desired conditions for better reuse. That way, the sub-site can be adapted and integrated into the outer site better.

[ang-zeyu]

Keep in mind that the outer site should be able to override things in the sub-site (without modifying it) as that is one of the desired conditions for better reuse. That way, the sub-site can be adapted and integrated into the outer site better.

Hmm in that case, isn't the above behaviours actually desired? (share also meaning the root site overrides the sub site's configurations)

[ang-zeyu]

I was thinking along the lines of:

root site - uses theme A
  sub site of a book - uses theme B suited for a book

when you build the root site, all pages in the sub site would use theme B, otherwise theme A.

There might be some usage benefits in keeping subsites independent like such.

desired conditions for better reuse

For this, I was thinking along the lines of <include>s / <import>s / <panel src="...">.

[damithc]

Hmm in that case, isn't the above behaviours actually desired? (share also meaning the root site overrides the sub site's configurations)

Yes, it is desired; the subsite should stand alone. It should not need to access the outer site. In addition, the outer site should be able to override subsite as necessary.

[ang-zeyu]

the outer site should be able to override subsite as necessary.

that has it's benefits as well. I'm personally fine with either behaviour, the current situation being easier to implement (no changes required)

Would this be completely a non-issue then? I feel like there's still something missing / unclarified though #1263 (comment) -
are there any other missing pieces in subsite support?

[damithc]

Would this be completely a non-issue then? I feel like there's still something missing / unclarified though #1263 (comment) -
are there any other missing pieces in subsite support?

I think it is good to think it through and clarify which things are overridable and specify how to override them. So, this issue is timely. Also, we may have to decide the default behavior for each. For example, we can say the outer site titlePrefix overrides the inner site titlePrefix by default, and provide a way to let the inner site keep its own title prefix (?) -- or vice versa, whichever way we decide.

In the case of CS2103, the se-book subsite is not directly plugged into the outer site. Rather, its content are integrated into the website via another layer of glue-code (in the se-book-adapted folder). I suspect this would be the situation most of the time i.e., the outer site will pick and choose what content to take from the inner site and where to put them. The outer site might not even want to reuse the structure of the inner site; rather, it will impose its own structure on the inner site's pages so that it integrates well with the outer site.

[ang-zeyu]

I think it is good to think it through and clarify which things are overridable and specify how to override them. So, this issue is timely. Also, we may have to decide the default behavior for each. For example, we can say the outer site titlePrefix overrides the inner site titlePrefix by default, and provide a way to let the inner site keep its own title prefix (?) -- or vice versa, whichever way we decide.

We can provide both options as well.

I think it's more intuitive to make it conventionally hierarchical - if a subsite's config leaves a field empty, we don't override the root site's config. The downside to this being that if you want to deploy the subsite independently, you'd have to maintain a separate set of configs (but that should be reasonable).

Certain fields will be the exception to this rule. Example baseUrl, which dosen't make sense to override, or the deploy config.

Side note: the implementation likely becomes much more complex by providing both options, which might not be worth the cost (making this issue lower priority).

subsites incorrectly share layouts with the root site

This is a little tricky though. Say we have

{
  page: "xx.md",
  layout: "xx"
}

and both the root site and subsite have the xx layout.

I suggest, if the above configuration was

• in the subsite config or the page's frontmatter itself, we look for the layout only in the subsite
  • the alternative being to look for the layout in the root site *as well
• in the root site config (where xx.md is a subsite page), we look for the layout only in the root site
  • alternative being to look for the layout in the subsite as well

The layout specified in the site.json overrides the one specified in the .

Related to the layout behaviour suggested above is this -- Say we have a generic page blob in the site config applying a certain layout, but I want a certain page to have a different layout. I could either a. create a whole separate entry for that page in site.json or b. override it in the page frontmatter itself, which is supposed to contain per-page configuration anyway.

I suggest reversing the above priority as a breaking change somewhere down the line too.

[damithc]

The usage scenario I have in mind is that the outer site simply picks and chooses which parts of the inner site to integrate into the outer site. That is, we don't think of the inner site as a separate site but just a folder containing more .md files. However, variables and nunjucks defined for the inner site should still work.

Are you thinking along the same lines or are you thinking of a different direction?

[ang-zeyu]

The usage scenario I have in mind is that the outer site simply picks and chooses which parts of the inner site to integrate into the outer site. That is, we don't think of the inner site as a separate site but just a folder containing more .md files. However, variables and nunjucks defined for the inner site should still work.

Are you thinking along the same lines or are you thinking of a different direction?

I'm thinking this, + layouts (subsite pages don't currently use subsite layouts but the root site's unlike variables) for a start

So, this issue is timely. Also, we may have to decide the default behavior for each. For example, we can say the outer site titlePrefix overrides the inner site titlePrefix by default, and provide a way to let the inner site keep its own title prefix (?) -- or vice versa, whichever way we decide.

After that we could look at providing configuration overriding:

root site.json
{
  "theme": "bootswatch-cerulean",
  "titlePrefix:" ...
}

sub site.json
{
  "theme": "bootswatch-sketchy",
}

so in the case the subsite would have the sketchy theme, but would inherit the plugins titlePrefix from the root site.json.