UnitsML official site

Introduction

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.

Content management

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.

Overview

Content management workflow involves the following phases:

1. Authoring: changing the contents of the repository. You’ll manipulate AsciiDoc files (.adoc file extension) and related files such as illustrations.

2. 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.)

3. 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.)

Setup

Pre-requisites

Make sure you have the installed:

• A text editor (you can use a simple editor like CotEditor on macOS or Notepad+ on Windows, or something more complex like VS Code with support for AsciiDoc preview)

• Git CLI

Authoring

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 .adoc files. Most site source files (.adoc and otherwise) have frontmatter at the beginning, inbetween the --- delimiters—that frontmatter. That frontmatter must specify the correct layout (see below) and your page’s title. After the frontmatter block, normal content (AsciiDoc, HTML, etc.) begins.

Documentation

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/.

Navigation sidebar

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.

The Deliverables page

That page (currently /docs/section-1/deliverables.adoc) is a special in that it contains code that initializes a deliverable browser. Regarding that page, feel free to add text before

Posts

Blog/news roll posts reside under /_posts/ directory. See the existing post for frontmatter example.

Other pages

(Section to be completed.)

Previewing site locally

Getting started

1. Ensure you have reasonable Ruby version (2.7.5 is recommended). Use rbenv to manage Ruby versions.

2. Run bundle from within site directory to install Ruby dependencies.

Building & serving

Run jekyll serve from within site directory.

Alternatively, build to HTML and serve separately with jekyll build && cd _site && python3 -m http.server.

To troubleshoot errors, append ` --trace` to build or serve command.

Development workflow

1. Ensure site builds and works normally, tests pass

2. Create your feature branch (git checkout -b my-new-feature)

3. Commit your changes (git commit -am 'Add some feature')

4. Push to the branch (git push origin my-new-feature)

5. Make a pull request