Rationale
See GitHub issue #545 for the work to migrate the page management system (JAM stack, Static Site Generation). The stated reasons for this migration effort include:
- The current Jekyll-based solution is fragile and brittle - dependencies can be frequently updated and typically rely on differing versions of shared libraries
- complex to learn and support - it's easy to install or use the wrong libraries and misconfigure the ruby environment so badly that you cannot preview pages
- does not support different versions per branch - as we begin to use two or more branches at once, it is important to keep the diverging features documented separately (in their own branch)
- Documentation is generated in Markdown, associated with each repository, moved to
open-horizon.github.iorepo when merged, and the site is generated in Jekyll with keywords abstracted out and inserted at page generation time.
Structure
Directives
Manual HTML element IDs
IDs are currently assigned using this syntax, which throws an acorn parsing error:
# Accessing management hub logs
{: #accessing_logs}
The proposed solution is to remove the colon and space from the tag and move it up to the previous line separated from the title by a space:
# Accessing management hub logs {#accessing_logs}
Code blocks with CSS className for styling
Code blocks are currently written using this pattern:
```bash
oc get pods --namespace kube-system | grep ibm-edge
```
{: codeblock}
The hanging colon directive at the end is causing an acorn parsing error. Proposed solution is to remove the trailing directive and edit site configuration to add className to all code blocks if still needed:
```bash oc get pods --namespace kube-system | grep ibm-edge ```