/web

www.openssl.org

Primary LanguageCSS

OpenSSL web pages

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 (---).

Recommendations

Building

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:

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:

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