This is the site for the UnitsML project, located at https://www.unitsml.org.
It is a Jekyll-based site created with the Open Project Jekyll theme.
Refer to their respective docs for details.
Unlike other sections, this section targets site author who does not necessarily have a software engineering background.
Note
|
This documentation covers macOS or Ubuntu Linux. |
Content management workflow involves the following phases:
-
Authoring: changing the contents of the repository. You’ll manipulate AsciiDoc files (
.adoc
file extension) and related files such as illustrations. -
Previewing your changes (optional): building and previewing the new version of the site locally without publishing. (This is not a strict requirement at early stages, you can skip straight to the next step and see your changes live. However, setting up for this step is beneficial since it allows you to preview your changes quicker.)
-
Version management: relaying your changes to upstream repository. This means others will see your changes. This also will cause the new version of the site to be published. (Publishing the new version may take a few minutes.)
Key sections are documentation pages (the largest) and news/blog posts. Apart from that there can be other standalone pages.
Note
|
You will be authoring site source using AsciiDoc syntax.
With AsciiDoc, your write plain text, and the result is rendered as HTML on the public site later.
Check out https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/
for a quick reference.
AsciiDoc is contained in Most site source files ( |
Documentation lives under the /docs/
directory.
All documentation source pages therein must specify layout: docs
in frontmatter.
The structure of the directory is reflected in the structure of URLs.
For example, file /docs/section-1/test-page.adoc
will be available under ap210.org/docs/section-1/test-page/
.
Documentation requires manual update when you add pages, retitle them or move them around.
Navigation across the docs lives separately from documentation files:
you can find it under /_layouts/docs.html
.
The YAML frontmatter of that file (between ---
delimiters`) contains
a key navigation
, under which documentation structure is described.
The sidebar is generated from this structure.
Blog/news roll posts reside under /_posts/
directory.
See the existing post for frontmatter example.
-
Ensure you have reasonable Ruby version (2.7.5 is recommended). Use rbenv to manage Ruby versions.
-
Run
bundle
from within site directory to install Ruby dependencies.