Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/openssl/web
www.openssl.org
https://github.com/openssl/web
website
Last synced: about 2 months ago
JSON representation
www.openssl.org
- Host: GitHub
- URL: https://github.com/openssl/web
- Owner: openssl
- Created: 2016-05-31T02:00:08.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-06-06T07:33:33.000Z (7 months ago)
- Last Synced: 2024-06-06T18:54:21.921Z (7 months ago)
- Topics: website
- Language: CSS
- Size: 145 MB
- Stars: 52
- Watchers: 39
- Forks: 75
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Support: support/acks.md
- Roadmap: roadmap.md
Awesome Lists containing this project
README
# 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:
``` yaml
---
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:
``` yaml
---
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
---------------
- 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 `
` and `
`, to make it distinct from
paragraphs around it.
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:
- [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 the `omc/data` repository)
- `general-policies`
(checkout of )
- `technical-policies`
(checkout of )
- `openssl`
(checkout of ,
`master` branch)
- `openssl-3.1`
(checkout of ,
`openssl-3.1` branch)
- `openssl-3.0`
(checkout of ,
`openssl-3.0` branch)
- `openssl-1.1.1-stable`
(checkout of ,
`OpenSSL_1_1_1-stable` branch)
The checkouts directory can be given to `make` with the `CHECKOUTS`
variable. It is important to use an absolute path:
``` console
$ make CHECKOUTS=/PATH/TO/checkouts
```
[Template Toolkit]: http://www.template-toolkit.org/
[Pandoc]: https://pandoc.org/
[Pandoc User's Guide]: https://pandoc.org/MANUAL.html#pandocs-markdown
[Markdown guide]: https://www.markdownguide.org
[Markdown guide extended syntax]: https://www.markdownguide.org/extended-syntax/
[Github Flavored Markdown]: https://github.github.com/gfm/
[OpenSSL::Query]: https://github.com/openssl/omc-tools/tree/master/OpenSSL-Query