This is the Metanorma project site (a Ribose Open Project Site) located at https://www.metanorma.org.
It is implemented as a Jekyll site with jekyll-theme-open-project theme.
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.jsWhenever you delete or rename a page, it’s important that you leave a redirect.
To leave a redirect, add an entry under redirect_from key in the frontmatter of the page where you want to redirect to.
For an example, see https://github.com/metanorma/metanorma.org/blob/main/_pages/author.adoc.
|
Important
|
Try to reduce such changes with careful planning, and never delete or rename pages without leaving a redirect. |
-
Settle on flavor and markup abbreviations.
-
Flavor abbreviation is not typically the same as organization abbreviation; usually it ends with "D"—e.g., M3AAWG is M3AAWG’s flavor abbreviation.
ImportantThe --typeflag 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>.
-
-
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.
TipAs 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-M3AAWG shows an example of more basic flavor docs.
-
-
Create flavor authoring docs entry page. Place
<lowercase flavor abbreviation>.adocunderauthor/, 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 %}
-
We will define that layout shortly.
-
-
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.adocandref.adocshould be provided under flavor docs root (can omit content). Topic and reference guide documents must live under correspondingly named sibling directories,topics/andref/. -
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. Seeauthor/m3aawg/sample.adocfor an example with default basic build instructions (via include), andauthor/iso/sample.adocfor an example with custom build instructions.
-
-
Add implementing gem under
_software/, filename should reflect the actual package (gem) identifier, usually it would bemetanorma-<lowercase flavor abbreviation>.adoc.See e.g.
_software/metanorma-ietf.adocfor an example. -
If defined, add data model spec under
_specs/, filename should reflect repository name, usually it would bemetanorma-model-<lowercase flavor abbreviation>.adoc.See e.g.
_specs/metanorma-model-iso.adocfor an example. -
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.org/<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: Usage path: /topics/ # References author/<flavor abbr>/topics.adoc items: # Implies author/<flavor abbr>topics/* files exist - title: 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
-
Add corresponding entry in the table under
_pages/flavors.adoc.
-
Ensure you have reasonable Ruby version
-
Run
bundlefrom within site directory to install Ruby dependencies
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/.
To make it watch for file changes and build automatically (which watches only the files specified in the above Inputs section), run:
make watchIf you want to be sure all outputs are cleaned prior to building, run:
make clean-watchThis section is only for deployment.
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.rcIf you have access to the bucket, run this.
export AWS_PROFILE=myprofile
source ro-site.rc
make uploadThe 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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent