OpenSSL web page sources are written in [Markdown], and possibly templated further using Template Toolkit.
Plain Markdown files must have the filename suffix .md.
Templated Markdown files must have the filename suffix .md.tt.
For page breadcrumbs purposes, every Markdown file must start with the
following YAML section, where {name} is replaced with the name this file
shall have in its part of the breadcrumbs:
---
breadcrumb: {name}
---In each directory where there are Markdown files, there must also be a file
dirdata.yaml, containing common data for that directory, which affects the
rendering of the sidebar and the common page breadcrumbs (the breadcrumb
value in each file will be appended to them). For example, in the directory
examples/, one might imagine a examples/dirdata.yaml looking like this:
---
breadcrumbs: |
[Home](..) : [Examples](.)
sidebar: |
# Examples
- [One example](example1.html)
- [Another example](example2.html)
---Please remember that all YAML must start and end with tripple dash lines
(---).
-
Let Markdown guide be your guide for writing Markdown files. The Markdown guide extended syntax adds a lot of useful possibilities.
If there's an alternative that Github Flavored Markdown understands, use that, as that makes reviewing easier.
If there's a need that isn't covered by the Markdown guide, refer to the Pandoc User's Guide, or use HTML, whichever is clearer.
-
Surround any table with
<p>and</p>, to make it distinct from paragraphs around it.
The Markdown files are rendered into HTML using Pandoc, see the Pandoc User's Guide for information on the Markdown syntax it understands and support.
Building the web pages is done through the Makefile, and requires
a number of programs to be installed:
- Template Toolkit. The Debian package is
libtemplate-perl - Pandoc. The Debian package is
pandoc - OpenSSL::Query, see its README.md for installation instructions.
git,python3,wget
It also requires a checkout of a number of repositories and branches. Some
of the repositories may need specific access. The Makefile requires that
they are all collected under one checkouts directory, with the following
layout:
data(checkout of theomc/datarepository)general-policies(checkout of https://github.com/openssl/general-policies.git)technical-policies(checkout of https://github.com/openssl/technical-policies.git)openssl(checkout of https://github.com/openssl/openssl.git,masterbranch)openssl-3.1(checkout of https://github.com/openssl/openssl.git,openssl-3.1branch)openssl-3.0(checkout of https://github.com/openssl/openssl.git,openssl-3.0branch)openssl-1.1.1-stable(checkout of https://github.com/openssl/openssl.git,OpenSSL_1_1_1-stablebranch)
The checkouts directory can be given to make with the CHECKOUTS
variable. It is important to use an absolute path:
$ make CHECKOUTS=/PATH/TO/checkouts