Metanorma Open Project Site

Introduction

This is the Metanorma project site (a Ribose Open Project Site) located at https://www.metanorma.com.

It is implemented as a Jekyll site with jekyll-theme-open-project theme.

Custom features

When adding a blog post, it’s possible to have an illustration that is replaced on hover with another illustration. To do that, use the following markup:

[.hoverable]
.Image title
[link="/assets/blog/image-1-on-hover.png"]
image::/assets/blog/image-1.png[Alt text]

And make sure widget JS is included via post’s frontmatter:

extra_scripts:
  - src: /assets/js/hoverable-illustrations.js

Content management

Adding a flavor

1. Settle on flavor and markup abbreviations.

   • Flavor abbreviation is not typically the same as organization abbreviation; usually it ends with “D”—e.g., M3D is M3AAWG’s flavor abbreviation.

     Important

     The --type flag given to Metanorma-CLI is expected to reference the same flavor abbreviation in lowercase.

   • Markup abbreviation usually takes the form of Ascii<uppercase flavor abbreviation>.

2. Settle on flavor authoring docs structure. Metanorma flavor documentation is usually split into following sections:

   • Getting started (markup mostly auto-generated)

   • Sample document play guide

   • One or more pages offering topic guides: how sections are formatted, how references are formatted, any specifics about build, etc.

   • One or more pages offering reference guides: a complete list of custom document attributes (either new attributes or attributes which behave differently compared to “base” Metanorma), a list of unsupported AsciiDoc features, etc.

     Tip

     As a rule, it is helpful to provide different angles through both topics and references: former for newer authors, and latter for more experienced authors. Really simple flavors can omit separate topics/references sections and just provide a single authoring guide page with any specifics. Metanorma-IETF shows an example of more complex flavor docs, Metanorma-M3D shows an example of more basic flavor docs.

3. Create flavor authoring docs entry page. Place <lowercase flavor abbreviation>.adoc under author/, with following contents:

   ---
   layout: <lowercase flavor abbreviation>-flavor (1)
   title: Metanorma for <uppercase flavor abbreviation>
   ---
   :page-liquid:
   
   {% include flavor-quickstart-steps.adoc flavor=layout.<lowercase flavor abbreviation>_flavor %}

   1. We will define that layout shortly.

4. Create flavor authoring docs. Create a directory author/<lowercase flavor abbreviation>/ (flavor docs root) and place .adoc files inside according to desired documentation structure. All files should specify frontmatter with the same layout as flavor docs entry page.

   • If topic and reference guides will be provided, index pages topics.adoc and ref.adoc should be provided under flavor docs root (can omit content). Topic and reference guide documents must live under correspondingly named sibling directories, topics/ and ref/.

   • Sample document guide should be placed in sample.adoc. It’s suggested to ensure that your sample document build process is consistent with other flavors, and that you use includes to avoid repetition, though you can provide custom instructions if needed. See author/m3d/sample.adoc for an example with default basic build instructions (via include), and author/iso/sample.adoc for an example with custom build instructions.

5. Add implementing gem under _software/, filename should reflect the actual package (gem) identifier, usually it would be metanorma-<lowercase flavor abbreviation>.adoc.

   See e.g. _software/metanorma-ietf.adoc for an example.

6. If defined, add data model spec under _specs/, filename should reflect repository name, usually it would be metanorma-model-<lowercase flavor abbreviation>.adoc.

   See e.g. _specs/metanorma-model-iso.adoc for an example.

7. Create layout named <lowercase flavor abbreviation>-flavor.adoc. The layout will contain extensive frontmatter and no content of its own, only the {{ content }} placeholder.

   Layout frontmatter structure is shown below. Fill in placeholders in angular brackets, square brackets denote optional elements:

   layout: flavor
   docs_title: Metanorma for <uppercase flavor abbreviation>
   title: Write <organization abbreviation> <documents|standards> with Metanorma
   
   <lowercase flavor abbreviation>_flavor:
     base_url: /author/<lowercase flavor abbreviation>
     title: <uppercase flavor abbreviation>
     title_org: <organization abbreviation>
     title_org_full: <full organization name, unpacking abbreviations>
     markup_name: <markup abbreviation>
   
     # Should be identical to filename (no extension) of the entry under `_software`
     # corresponding to the gem implementing the flavor.
     implemented_by: <software entry>
   
     build:
       # (self-explanatory)
       cli_flags: "--type <lowercase flavor abbreviation>"
   
     # Sample document, recommended as a quick-start for new authors
     sample:
       title: <sample document title>
       repo_url: <URL of repository, including path to the exact file, if needed>
   
       # (optional)
       # If you have self-containing HTML file showcasing built sample document for the new flavor,
       # you can place it under `_pages/`, and reference filename here this way:
       rendered_url: https://www.metanorma.com/<built-sample-html-filename>/
       # …or, if it’s available elsewhere, this way:
       rendered_url: https://metanorma.github.io/…/
   
     # Desired navigation structure. Example given.
     navigation:
       items:
       - title: Get started
         path: /                            # References author/<flavor abbr>.adoc
       - title: Sample
         path: /sample/                     # References author/<flavor abbr>/sample.adoc
       - title: Using the flavor
         path: /topics/                     # References author/<flavor abbr>/topics.adoc
         items:                             # Implies author/<flavor abbr>topics/* files exist
         - title: <markup abbreviation> markup
           path: /topics/markup/            # References author/<flavor abbr>/topics/markup.adoc
           items:                           # Implies author/<flavor abbr>/topics/markup/* files exist
           - title: Example
             path: /topics/markup/example/  # References author/<flavor abbr>/topics/markup/example.adoc
       - title: Reference guides
         path: /ref/
         items:
         - title: Document attributes
           path: /ref/document-attributes/
   
     # Key links to documentation (relative) or external resources (absolute)
     # instrumental for new authors. Example given.
     docs_entry_points:
       - path: ./topics/markup/example/
         title: quick markup example
       - path: ./topics/
         title: topics
       - path: https://github.com/metanorma/rfc-in-asciidoc-template
         title: document template
   
     # (optional)
     # Should be identical to filename (no extension) of the corresponding entry under `_specs`,
     # if any.
     data_models: <specs entry>
   
     # (optional)
     # Use for “experimental” flavors not ready for production.
     experimental: yes

8. Add corresponding entry in the table under _pages/flavors.adoc.

Development

Getting started

• Ensure you have reasonable Ruby version

• Run bundle from within site directory to install Ruby dependencies

Serving site preview

• Run jekyll serve from within site directory

Structure

This repository contains a _config.yml for specifying the directory structure, metadata, build defaults, etc.

Site data is located in this directory and the resulting build is created under _site/.

Inputs

All source files are inside the _jekyll/ directory, as specified in _config.yml.

Outputs

All output files live inside the _site/ directory, and its content have been gitignore-d.

Usage

Preparation

To begin developing,

make prep

which would install the necessary Ruby gems for you.

Auto-build

To make it watch for file changes and build automatically (which watches only the files specified in the above Inputs section), run:

make watch

If you want to be sure all outputs are cleaned prior to building, run:

make clean-watch

Just build

The non-watching equivalents for the above are simply:

make build

make clean-build

Deployment

This section is only for deployment.

Configuration

Configure the hostname and region in the ro-site.rc file as you know it.

cp ro-site.rc.template ro-site.rc
vi ro-site.rc

Uploading to S3

If you have access to the bucket, run this.

export AWS_PROFILE=myprofile
source ro-site.rc
make upload

Clear CloudFront caching

The sites are accessed via CloudFront. If you’re seeing stale data after make upload, most likely the CloudFront cache needs to be invalidated.

Your AWS account must be authorized to invalidate the CloudFront cache for this distribution.

export AWS_PROFILE=myprofile
source ro-site.rc
make clear-cf

Workflow

1. Ensure 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. Create new Pull Request