s9y documentation (Github Pages)

This is the documentation for Serendipity.

Contributing

Documentation is maintained in Markdown (.md) files using the kramdown library to transform it to HTML though Jekyll on GitHub pages.

Building locally

To build the site locally, please follow GitHub's instructions for using Jekyll with Pages.

Markdown usage

• Some heading levels are reserved for other elements of the site layout. The first heading level you may use in Markdown files is h2 (## in Markdown), so you have h2 to h6 available. If you feel that a section needs more structuring, it should probably be split up in two or more sections.
• Note that three backticks only introduce a code block in GitHub flavored Markdown. In generic Markdown (which is what we have in Jekyll), code blocks are generated by indenting the code 4 spaces or a tab (please use 4 space here).
• Also, a span of code in copy text (i.e. <code> within <p>, not within <pre>) is limited by single backticks, not three backticks.
• To set internal links (i.e. links to other pages of the docs), please use relative links starting with a /, and always link to the HTML version of the page; for example /docs/faq/index.html

Generating CSS + JS assets

The CSS in css is generated from Sass source files, the JS in scripts is combined from various sources, and both are optimized by a build process. Since these assets are supposed to be re-used on multiple s9y platforms, they have been moved to a separate repository. Please consult the README there for build instructions.

Jekyll usage

• Every Markdown file needs a YAML front matter with at least a sensible title. Like this:

---
title: Documentation
---

• You can also set the layout for a page in the YAML front matter. See _layouts for available layouts.

---
layout: home
title: Serendipity
---

• To add a table of contents to a page, add this add the start of an .md file after the YAML front matter:

<h2>(title of the page)</h2>

* TOC
{:toc}

This will automagically generate a table of contents based on the headings in that pages content, i.e. a list of links to said headings. (Of course, this only makes sense if the page actually contains headings and a logicaly heading hierarchy.) Please note that you have to write the page title heading in HTML, otherwise it would be included in the TOC.

Adding images

• Any image used (as an <img>) in the docs should be available in 2x format for HDPI screens. That means that it needs to be twice the size of the largest instance of the image. For example, if the largest version of an image displayed is 640x320 pixels, it should be supplied in 1280x640 pixels.
• For image formats, the rule of thumb should be “PNG, unless that's too large”. So, what is “too large”? Hard to say because it depends on the content and importance of the image. In general, please use JPG for photos or screenshots and PNG for everything else.
• Please store images used in the docs in the img directory in a subdirectory, especially if it's a group of images. Try to pick a logical name for the subdirectory.