search

metanorma / metanorma.org

Official Metanorma website
https://www.metanorma.org
MIT License
7 stars 7 forks source link

Integrating Metanorma pages into Jekyll #7

Open ronaldtse opened 6 years ago

ronaldtse commented 6 years ago

We have a number of specs written in Metanorma format, such as in MetanormaISO, in their own git repos.

We wish to submodule them in metanorma.com (and other Open Sites) and display them on the static site.

This task is to build a Jekyll plugin that automatically invokes the Metanorma toolchain to build those files into HTML output, and incorporate that HTML output (and styled correctly) into the static site.

cc: @opoudjis could you chime in your thoughts? Thanks!

strogonoff commented 6 years ago

To expand on the two aspects of this feature:

  1. We want to integrate specification sources from their repos into project sites, similar to what Open Project framework does with software docs. The requisite functionality exists, but has to be properly exposed and documented where it concerns specs (this is in the works).

  2. We want to build the specs from their sources during project site build. The new thing this issue raises is that we should support building specs from Metanorma-structured sources. (With software docs Open Project framework expects its own simple structure[0].) Ideally I’m also seeing this happening through a specialized plugin, similar to the one that adds support for AsciiDoc files to Jekyll.

In meantime specs are included in their rendered form, which is not pretty (spec example from RNP).

Not going in detail about the use of submodules here, as I believe we’re covering that under https://github.com/riboseinc/jekyll-theme-open-project-helpers/issues/1. (Speaking of that issue, I can commit to going with submodules, but I’d like to understand the purpose that would that serve and whether Git submodules offer the requisite functionality.)

This issue relates to #5.

[0] https://github.com/riboseinc/jekyll-theme-open-project/issues/24

ronaldtse commented 6 years ago

Regarding submodules -- we can also clone them for the latest version to save ourselves the need of "updating" the main repo.