126 lines
8.1 KiB
Markdown
126 lines
8.1 KiB
Markdown
# Site Content
|
|
|
|
You will need to create a site folder in `/projects/manager/sites/<site-name>` (ignored by `git`), create a `config.json` file to define how the site generates pages, and have some sort of content in order for the site to generate. Before previewing the site, run `npm run set-current -w=manager --site=<site-name>` so that the site is linked to the frontend.
|
|
|
|
## `config.json`
|
|
|
|
Without this file properly set up, your site will not function. There are a few key fields to define here. Consider the following example:
|
|
|
|
```json
|
|
{
|
|
"routes": {
|
|
"/": {
|
|
"template": "markdown",
|
|
"content": "/content/home.md",
|
|
"stylesheetUrls": [
|
|
"/content/home.css"
|
|
],
|
|
"id": "home",
|
|
"fullTitle": "Home | My Site",
|
|
"title": "Home"
|
|
},
|
|
"/about": {
|
|
"template": "markdown",
|
|
"content": "/content/about.md",
|
|
"stylesheetUrls": [
|
|
"/content/about.css"
|
|
],
|
|
"id": "about",
|
|
"fullTitle": "About | My Site",
|
|
"title": "About"
|
|
},
|
|
"/gallery": {
|
|
"template": "gallery-list",
|
|
"config": "/content/gallery.json",
|
|
"stylesheetUrls": [
|
|
"/content/gallery.css"
|
|
],
|
|
"id": "gallery",
|
|
"title": "Gallery",
|
|
"fullTitle": "Gallery | My Site",
|
|
"view": {
|
|
"title": "$ENTRY",
|
|
"fullTitle": "$ENTRY | Gallery | My Site",
|
|
"stylesheetUrls": [
|
|
"/content/gallery.css"
|
|
]
|
|
},
|
|
}
|
|
},
|
|
"header": [
|
|
{
|
|
"path": "/",
|
|
"displayName": "Home"
|
|
},
|
|
{
|
|
"displayName": "Galleries",
|
|
"children": [
|
|
{
|
|
"displayName": "Anthro",
|
|
"path": "/anthro"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"path": "/about",
|
|
"displayName": "About"
|
|
},
|
|
{
|
|
"path": "https://example.org",
|
|
"displayName": "Home Site",
|
|
"target": "_blank"
|
|
}
|
|
],
|
|
"id": "my.example.org",
|
|
"stylesheetUrls": [
|
|
"/content/base.css"
|
|
],
|
|
"tags": "/content/tags.json",
|
|
"themes": {
|
|
"dark": {
|
|
"displayName": "Dark",
|
|
"type": "dark",
|
|
"url": "/content/dark.css"
|
|
},
|
|
"light": {
|
|
"displayName": "Light",
|
|
"type": "light",
|
|
"url": "/content/light.css"
|
|
}
|
|
},
|
|
}
|
|
```
|
|
### Routes
|
|
|
|
Routes is the most important field here. It defines what HTML pages get generated by the static site generator. It is a key-value object where the key represents the intended URL of the page; this must always start with "/" (a route keyed by just "/" will represent the home page, e.g.`example.org/index.html` otherwise shortened to `example.org`).
|
|
|
|
The `template` field determines which view template is used when generating the page. See [templateType.d.ts](/libs/types/src/content/templates/templateType.d.ts) for the full list of currently supported template types. The full config for routes is defined in [routing.d.ts](/libs/types/src/config/routing.d.ts); at minimum, routes follow the `SharedRouteDefinition`. General templates will just generate a main page, while list-related templates like `article-list` and `gallery-list` have a list page (the main config) and a child "view" page (the `view` field in the main config) (e.g. if you have a `gallery-list` at `/gallery`, the main config will be for `/gallery` and the `view` config will be used for `/gallery/view?id={entry}`).
|
|
|
|
Depending on the template type, there may be `config` and/or `content` fields. Both of these are remote files that are fetched when the page first starts to load. `content` is used typically by generic templates that directly load some sort of `content`; `markdown` templates, for example, directly pull text from a markdown file, so when `"template": "markdown"`, `"content": "/content/path/to/markdown.md"`. `config` is used by more complex templates. List templates, for example, define a list of `entries`. In order to see what config you need, look for the corresponding template type name in [the types folder for templates](/libs/types/src/content/templates). Parsing these can be complex, so separate guides will be available for creating those templates.
|
|
|
|
The `id` of the page is used for identifying the page in code for caching purposes. `title` is a display-name for the route used in breadcrumb navigation/etc. `fullTitle` is the display-name for the page in the browser tab. `stylesheetUrls` is an array of strings linking to stylesheets that will be appended to the page. These are appended when navigating to the page and removed when navigating away from it.
|
|
|
|
`scriptUrl` allows loading an optional script file containing callbacks that are executed based on page events; these must be defined at the end of your script file in order to be used like so:
|
|
|
|
```js
|
|
export const callbacks = {
|
|
onPageClosed,
|
|
onPageLoaded,
|
|
}
|
|
```
|
|
|
|
All callbacks are optional. `onPageClosed` is called when the user is leaving the page they are currently on, which is useful if you have made some sort of modification to the page that may unintentionally be transferred to the next. `onPageLoaded` is called when the current page route loads; each view template emits a `loaded` event when it is finished loading its config and executing any tasks related to loading the template. Note that this doesn't necessarily mean asyncronous data will be loaded into view when this executes, simply that the main view is marked `ready` and will have the main template structure in place.
|
|
|
|
### Other Fields
|
|
|
|
`id` is used for identifying the site in browser cookies. This is important to allow for remembering certain things like if the user wanted to permanently hide gallery warnings or if the user picked a certain site theme.
|
|
|
|
`header` is an array of objects which define entries for site navigation. If you want to directly link a page, set the `path` of the page to the relative url of the page. You can optionally set `target` to set the `<a>` tag's `target` (e.g. opening in a new tab instead of same tab with `_blank`). If you want to add a drop-down of links, set `children` instead of `path`; `children` is recursive, in that it is an array of the same shape of objects found directly in `header`, which can either be links or a nested drop-down. Whether you're adding a drop-down of links or a direct link, remember to set `displayName` to set the link's text.
|
|
|
|
`stylesheetUrls` is the same as the `stylesheetUrls` found in the routes described above, with the exception that the root config.json `stylesheetUrls` are loaded/shared for every single page. `themes` is a special collection of stylesheets - it is a key-value object where the key is the id of the theme. `displayName` is what is displayed in the theme picker dropdown to the user; `type` describes what type of theme it is so that the frontend can default to a theme respecting the user's browser/system theme (see [themes.d.ts](/libs/types/src/config/themes.d.ts) for supported types); `url` is of course the url to the CSS file itself.
|
|
|
|
`tags` is used for definining filters based on tags assigned to entries in list-related templates. `tags` can either be a link to a JSON file or directly be embedded. In either case, it is an array of objects with the following fields: `displayName` (what the user sees on the list page's filters panel); `category` (optional, used for dividing related tags in the filters panel; uncategorized tags will appear at the top of the filters panel, and categorized tags will appear in subheadings); and finally `tagId` (identifies the tag used by list entries).
|
|
|
|
## Other Site Content
|
|
|
|
You are free to structure your site's content however you want, so long as `config.json` is directly in the root of the main site folder, and so long as it is understood that all files in this folder are assumed to be located at `/content/**` on the web-host. For example, if you have a site in the `/projects/manager/sites` folder named `my.example.org`, this `my.example.org` becomes `https://my.example.org/content` when the site is built and pushed to the host, assuming you are using the default setup used by the development/build scripts described in the ReadMe. `/projects/manager/sites/my.example.org/stylesheets` becomes `https://my.example.org/content/stylesheets`, `/projects/manager/sites/my.example.org/galleries/my-gallery.json` becomes `https://my.example.org/content/galleries/my-gallery.json`, and so on.
|