**ℹ️NOTE:** Running locally will show unpublished content that uses the `published: false` convention in frontmatter. Content with `published: false` will not be available on staging or production.
When you run `yarn start` the CSS and JS is built in parallel with the eleventy build. Once up and running both eleventy and the JS and CSS build scripts watch for changes. When something changes the site is re-built.
In development Eleventy knows nothing about the CSS and JavaScript builds. For automatic reloading of the JS and CSS, each script uses a fetch to the public API to tell browserSync there is new code and it reloads it for you.
Building for production is slightly different. The Eleventy process and the JS and CSS builds happen in series. Then a 3rd `asset-pipeline` process initiates and takes the the built content from `./build` directory and runs it through various optimizations.
All of this means that we can serve the site with far-future `Expires` headers. If the resource is in the browser's cache, the browser won't even make a request for it. To break the cache, the resource's URL needs to change. When something is updated and the script is re-run, the hash in the filename will change, so the new filename won't be cached and the browser will know to fetch it. This helps the site be fast.
Whilst the `asset-pipline` script is custom, it leverages a lot of existing libs where possible, these include Terser, postHTML, postCSS, and various plugins.
For the `asset-pipeline` script to do its thing, all you need to do is refer to all assets with a path beginning with `/assets/`. If you do that, everything else is handled for you ✨
2. Add a node with appropriate attributes, in the appropriate location, for the new page. See below: [Understanding the `pages.json` structure](#understanding-the-pagejson-structure).
3. Create a new page, nested inside a folder struture that matches the URL path. For example, for permalink `/documentation/develop/best-practices-for-collecting-user-data-consents/`, you would create a file called `best-practices-for-collecting-user-data-consents.md` and place it in `documentation ▶︎ develop`.
- When creating page sections that should be listed in the table of contents, add an `id` attribute to the section container that matches the `subpageitems` entry added to `pages.json`. If your layout requires several sections for one table of contents entry, nest your sections inside a containing element which has the `id` attribute.
- Rule for creating section `id`s: use the `h2` title of the section, converted to lowercase, spaces replaced with dashes, all non-alphanumeric characters removed. For example, the section `h2` title "Know your privacy settings" would be converted to `know-your-privacy-settings` for the section `id`.
- Each page has a `title` and `url` attribute.<br>
**ℹ️NOTE:** The `url` attribute must exactly match the `permalink` attribute of the page's front matter _(including leading and trailing slashes)_.
- Pages may also have a `subpageitems` node for sections within the page to be referenced in the table of contents for that page:
- Each `subpageitem` node has a `title` and `id` attribute. The value of `id` matches the `id` attribute of the section container.<br>
(**ℹ️NOTE:** `id`s must be added to the containing element, rather than the heading element, of the section. This ensures that highlighting for the section remains active, even when the section title is out of view.)
- Overview pages have `category` nodes for each of their contained (sub) `categories`.
- Categories have a `category` attibute (which denotes the category title), and a `pages` attribute (which lists sub-pages of the overview page).
- The Documentation Topics section pages are nested inside a `subfolderitems` node, which creates the dropdown panel.
If you don't want the page to be labelled as a draft (such as and when it's ready), remove `"draft-label": true` from the relevant entry in `data/content-guidelines-pages.json`.
The site is auto-deployed on commits to `master` to https://extensionworkshop.allizom.org/. You can check the version with [the stage version link](https://extensionworkshop.allizom.org/__version__).
Tags matching `^20\d{2}\.\d{2}\.\d{2}(?:-\d+)?$` regular expression will be deployed to https://extensionworkshop.com/. You can check the version on production with [the production version link](https://extensionworkshop.com/__version__).
