⭐️ Welcome to RFC Jekyll! ⭐️
This is a template to help you render an RFC document (or other standards document) on GitHub pages assembled from markdown files in multiple repositories. As a stong example of this secnario, we render it here with the opencontainers specs. Notably:
You can clone the repository right to where you want to host the docs:
git clone https://github.com/vsoch/rcf-jekyll ./docs
cd docs
To edit configuration values, customize the _config.yml. This includes details like the site title and basename.
The pages folder contains subfolders that are each examples of specs. For example, pages/images-spec includes multiple markdown files that are rendered from opencontainers/image-spec.
The _data/specs.yaml file defines shared attributes for an
entire spec folder. For example, let's take a look at this data file's definition
for image-spec
:
# This file holds shared metadata for a directory of specs
image-spec:
name: Image Spec
group: Open Containers Initiative (OCI)
github_repo: opencontainers/image-spec
default_version: v1.0.1
versions:
- v1.0.1
# Courtesy list of pages relative to site root to link
pages:
- image-spec/
- image-spec/annotations/
- image-spec/config/
- image-spec/considerations/
- image-spec/conversions/
- image-spec/descriptor/
- image-spec/image-index/
- image-spec/image-layout/
- image-spec/layer/
- image-spec/manifest/
- image-spec/media-types/
The various urls are used to define relative paths in the repository. The list
of pages (optional) will render a left side navigation to give the reader
context of all the documents included for a spec. Importantly, the key image-spec
at the top is used to lookup this metadata. Finally, the list of versions should
correspond to releases. If a release isn't given in the browser as a variable,
then we fall back to the default_version
variable.
Now we can look at an index.md
in pages/image-spec/index.md that is considered the
root of a spec:
---
layout: page
title: The OpenContainers Image Spec
id: IMAGE-SPEC
permalink: /image-spec/
spec: spec.md
# data key from _data/specs.yaml
key: image-spec
---
Note the key image-spec
will be used for the lookup. We primarily need to know
the name of the markdown file that will render into the page (spec.md
) and then
custom, page-specific attributes like the permalink and title.
Now let's say that we have a second markdown file linked from this spec called manifest.md
.
The template will find these links and render them into relative urls, so we also add
pages for them. In the case of manifest.md
the metadata would be almost the same,
but we'd update the name of the spec from spec.md
to manifest.md
and important
we would have the permalink be a relative path to it's parent, image spec:
---
layout: page
title: The OpenContainers Image Manifest Spec
id: IMAGE-SPEC-MANIFEST
permalink: /image-spec/manifest/
spec: manifest.md
parent: image-spec
key: image-spec
---
You'll notice a new field - parent. This is here so that we can correctly format links in the correct namespace. The reason for this metadata is because we render the pages doing the following:
raw_url
+ /
+ spec
raw_url
so the image renders..md
extension and turn it into a path. This means that the final url looks like a relative path of the filename. (E.g., manifest.md linked relatively turns into manifest/
linked from the current page, or /image-spec/manifest/
.Thus, to add a new document you should:
This means that when adding a new spec, you will need to do work once to go through these steps, but then you never need to update it again. The spec will load dynamically whenever the site is needed, and there is no rebuild necessary.
If you want to add a new OCI document and are having trouble, please open an issue to request it to be added.
Depending on how you installed jekyll:
jekyll serve
# or
bundle exec jekyll serve