Skip to content

Latest commit

 

History

History
331 lines (251 loc) · 10.1 KB

README.adoc

File metadata and controls

331 lines (251 loc) · 10.1 KB
Raw

Metanorma Open Project Site

Build Status Build Status

Introduction

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.

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

Avoiding dead links with redirects

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

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., M3AAWG 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-M3AAWG 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/m3aawg/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.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

  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