mackenzii/docs/content.md

Site Content

You will need to create a site folder in /projects/sites/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=sites --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:

{
  "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 for the full list of currently supported template types. The full config for routes is defined in 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. 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:

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 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/sites/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/sites/sites/my.example.org/stylesheets becomes https://my.example.org/content/stylesheets, /projects/sites/sites/my.example.org/galleries/my-gallery.json becomes https://my.example.org/content/galleries/my-gallery.json, and so on.