Writer's Guide

Learn how to create your documentation content.

This page helps you to get started with your documentation and describes available formatting in this template.

Get started

To get started you can modify this demo documentation or remove all contents of ./pages and ./media directories.

This Writer's Guide is also available at official META Platform Codebase.

Directory structure

META Doc compiles HTML and Markdown files into pages and page sections. Learn how to structure your documentation.

Pages

Following files and directories:

./pages/Root_section_A.md
       /Root_section_B.md
       /Page_A/Page_section_1.md
              /Page_section_2.html

will result in:

- Root section A
- Root section B
+ Page A
  - Section 1
  - Section 2

Directory pages is where your documentation source exists.

  • Each subdirectory is parsed as a Page.
  • Each file is parsed as page Section.

Look at example for better understanding.

Also take a look at following or continue reading.

Site

./site/index.html
      /page-1/index.html
             /sub-page/index.html
      /page-2/index.html
      /page-3/index.html

Directory site is where your documentation HTML is generated.

This directory is always cleared and content is re-generated.

So do not modify it's content.

Media

./media/screenshot.png
       /my_icon.png
       /package.zip
       /...etc...
Using constant in makrdown link:
[Some link]({{media}}/media_file.png)

Put your images and files into media directory.

This directory is directly copied into site/media directory.

You can reference to this site directory in your documentation files by using media constant. Read more about constants.

Template

./template/default.jade
          /another_template.jade
          /assets/main.css
                 /header.png
                 /...etc...

Directory template is optional.

If present then template in this directory is used. By default META Doc is using it's default template packed with module.

Templates are using JADE templating engine.

config.json

{
  "title": "My documentation",
  "header_title": "My documentation",
  "header_github": "https://github.com/metaplatform/meta-doc"
}

File config.json contains global documentation configuration.

Configuration object is used mostly by templates.

See Global configuration section for more details.

Special files

Files and directories prefixed by underscore, eg.: _hidden.md are ignored and not compiled as sections.

One of these special files are _excerpt.md and _excerpt.html. See Excerpt section.

Naming

Section.md        -> Section
Section.html      -> Section
1_Section.md      -> Section
01_Section.md     -> Section
001_Section.md    -> Section
My_section.md     -> My section
Another_file.html -> Another file

Labels of pages and sections are generated from filename by following rules.

  • Underscores are replaced with spaces
  • Number at beginning is stripped out
  • File extension is stripped out

Ordering

01_First_section.md    -> First section
02_Second_section.md   -> Section section
03_Third_section.md    -> Third section
Another_section.md     -> Another section

Pages and sections are ordered ascending by their filenames.

To order it just prefix filename by a number. It will be stripped out.

Look at example for better understanding.

Sections

Sections are visualy separated parts of page with anchors. So you can easily navigate between them.

Sections can be written using Makrdown or HTML.

Sample Makrdown section

Section.md

# Heading 1
Some paragraph

- List item
- List item

Using Markdown

To create Markdown section just created a new file with .md extension.

Using Markdown is recommended because it suports easy content editing and most of additional formatting functions.

Take a look at this Markdown cheatsheet.

If you will use HTML files then you must use template CSS classes directly.

Sample HTML section

Section.html

<h1>Heading 1</h1>
<p>Some paragraph</p>
<ul>
    <li>List item</li>
    <li>List item</li>
</ul>

Using HTML

To create HTML section just created a file with .html extension.

Contents of HTML file is directly rendered by template.

Constants and shortcodes

You can use constants and shortcodes both in Markdown and HTML sections.

Look at Constants and Shortcodes sections.

Pages

Each directory is compiled to a page and it's files are compiled as page sections.

But you can modify some behaviour using page configuration file.

Page configuration

To configure a page just create config.json file into page directory. This also aplies to root directory.

Following configuration properties are available for this default template:

Sample page configuration

./pages/My_Page/config.json

{
    "icon": "school",
    "slug": "getting-started",
    "hidden": false,
    "template": "my-template",
    "page_title": "Getting Started page"
}
Property name Description
icon Specifies MDI icon name without mdi- prefix.
slug Specifies custom URL slug for page that will be used instead of generated one.
hidden Boolean value. If true page is then excluded from navigation tree but can be accessed directly by URL.
template Specifies alternative template name - without .jade file extension.
page_title Overrides page title which is set to page label by default.

Page configuration properties also overrides default configuration. So you can set for example different description or keywords for each page.

Sample excerpt

_excerpt.md

# Writer's guide
Learn how to create your documentation content.

This sample page helps you to get started with your documentation and describes available formatting in this template.

Page Excerpt

Excerpt is short visual introduction to page contents. It is displayed at the top of page with icon and background.

To display excerpt you have to create file _excerpt.md or _excerpt.html in a page directory.

Excerpt icon can be specified using page config. If not specified then default icon is used.

Page excerpt screenshot

Well organized structure

01_Page_1
02_Page_2
03_Page_3
04_Section_1.md
05_Section_2.md
06_Section_3.md
_excerpt.md

Page directory

Page directory is automatically generated overview of child pages with icons and labels.

For the best results group subpages together.

Page directory screenshot


:::sidecode
## Heading
Optional description

```javascript
//Sample javascript code
console.log("Hello world!");
```
:::
		

Sidecode

Sidecode is special formatting block which displays content on right dark side (on desktop resolution). As it's name suggests it is designed for code examples aside of descriptive section contents.

If you are browsing this site in desktop resolution you can notice sidecode blocks aside of entire page.

To define sidecode in Markdown you can use :::sidecode block notation as example on right side demonstrates.

Shortcodes

Shortcodes adding extra formatting functionality. Shortcodes are enclosed in double brackets - see example codes.

Icon

[[icon school /]]
[[icon book-open /]]
[[icon code-tags /]]
[[icon name /]]

Adds MDI icon.

Attribute name specifies icon name without mdi- prefix.

or or

Link

[[link href=http://www.google.com ]]Link to google[[/link]]
[[link href=http://www.google.com target=_blank ]]Link to google which opens in new window[[/link]]
[[link href=target_url target=link_target ]]Link label[[/link]]

Adds hyperlink with support of target attribute.

Link to google
Link to google which opens in new window

Call-to-action button

[[cta href=http://www.google.com/ target=_blank ]]Open google[[/link]]
[[cta href='http://www.google.com/' ]][[icon arrow-right-bold-hexagon-outline /]]Open google[[/link]]
[[cta href=target_url target=link_target ]]Button label[[/link]]

Adds nice visual button with hyperlink.

Open google

Open google

Markdown parser rewrites double-quotes to entities so if you need quotes in shortcode arguments you must use single '...' quotes.

Icons

Using MDI icons

<i class="mdi mdi-book-open"></i>
[[icon book-open /]]

This template uses Material Design Icons (MDI) package.

Icons can be added directly via CSS class or using shortcode.

You can browse available MDI icons on local icons index page.

Alert boxes

Alert boxes displays important content by expressive way.

Code example

Markdown

::: info
**Message title!** {.title}
Sample message contents.
:::

Information box

Message title!

Sample message contents.

Code example

Markdown

::: success
**Message title!** {.title}
Sample message contents.
:::

Success box

Message title!

Sample message contents.

Code example

Markdown

::: warning
**Message title!** {.title}
Sample message contents.
:::

Warning box

Message title!

Sample message contents.

Code example

Markdown

::: alert
**Message title!** {.title}
Sample message contents.
:::

Alert box

Message title!

Sample message contents.

Heading labels

This template comes with various heading labels which visualise various HTTP methods and other properties.

Labels can be used in heading and in sidecode block headings.

Label of GET method

### /http/get/example {.tag .get}
This block demonstrates usage of GET label.
Main purpose of this label is to document API endpoint method in an expressive way.

/http/get/example

This block demonstrates usage of GET label. Main purpose of this label is to document API endpoint method in an expressive way.

Label of POST method

### /http/post/example {.tag .post}
This block demonstrates usage of POST label.
Main purpose of this label is to document API endpoint method in an expressive way.

/http/post/example

This block demonstrates usage of POST label. Main purpose of this label is to document API endpoint method in an expressive way.

Label of PUT method

### /http/put/example {.tag .put}
This block demonstrates usage of PUT label.
Main purpose of this label is to document API endpoint method in an expressive way.

/http/put/example

This block demonstrates usage of PUT label. Main purpose of this label is to document API endpoint method in an expressive way.

Label of DEL method

### /http/del/example {.tag .del}
This block demonstrates usage of DEL label.
Main purpose of this label is to document API endpoint method in an expressive way.

/http/del/example

This block demonstrates usage of DEL label. Main purpose of this label is to document API endpoint method in an expressive way.

Label of OPTIONS method

### /http/options/example {.tag .options}
This block demonstrates usage of OPTIONS label.
Main purpose of this label is to document API endpoint method in an expressive way.

/http/options/example

This block demonstrates usage of OPTIONS label. Main purpose of this label is to document API endpoint method in an expressive way.

Label of HEAD method

### /http/head/example {.tag .head}
This block demonstrates usage of HEAD label.
Main purpose of this label is to document API endpoint method in an expressive way.

/http/head/example

This block demonstrates usage of HEAD label. Main purpose of this label is to document API endpoint method in an expressive way.

Label of PROPERTY endpoint

### /http/prop/example {.tag .prop}
This block demonstrates usage of PROP label.
Main purpose of this label is to document property endpoint in an expressive way.

/http/prop/example

This block demonstrates usage of PROP label. Main purpose of this label is to document property endpoint in an expressive way.

Label of FUNCTION endpoint

### /http/func/example {.tag .func}
This block demonstrates usage of FUNC label.
Main purpose of this label is to document for example RPC endpoint in an expressive way.

/http/func/example

This block demonstrates usage of FUNC label. Main purpose of this label is to document for example RPC endpoint in an expressive way.

Label of LIVE endpoint

### /http/live/example {.tag .live}
This block demonstrates usage of LIVE label.
Main purpose of this label is to document for example reactive (socket) endpoint in an expressive way.

/http/live/example

This block demonstrates usage of LIVE label. Main purpose of this label is to document for example reactive (socket) endpoint in an expressive way.

Label of ATTRIBUTE

### type {.tag .attr}
This block demonstrates usage of ATTR label.
Main purpose of this label is to document various attributes.

type

This block demonstrates usage of ATTR label. Main purpose of this label is to document various attributes.

Label of EVENT

### onClick {.tag .event}
This block demonstrates usage of EVENT label.
Main purpose of this label is to document object event in an expressive way.

onClick

This block demonstrates usage of EVENT label. Main purpose of this label is to document object event in an expressive way.

Images

<img src="/assets/my-image.png" />

or in Markdown

![Alt text](/assets/my-image.png)

Images can be inserted using markdown-way or via HTML.

Maximal width of image is set via CSS to 100% of section width.

So do not set image width and height properties or it will be deformed!

Buil-in lightbox

#With image as a thumbnail
[![Directory screenshot][/media/screenshot-directory.png]](/media/screenshot-directory.png)

This [link to an image](/media/screenshot-directory.png) will be opened in a lightbox.
This [[link href=/media/screenshot-directory.png target=_blank ]]link to an image[[/link]] will be opened in a new tab.

If you create a link to an .jpg or .png image and link target is not _blank then image will be opened in a lightbox.

This link to an image will be opened in a lightbox.
This link to an image will be opened in a new tab.

./pages/01_Page_1/...
./pages/02_Page_2/...
./pages/03_Page_3/...
./pages/04_Page_4/...
./pages/_excerpt.md
./pages/config.json

config.json:

{
    "template": "landing"
}

Landing page template

Default documentation template comes with landing page sub-template.

Landing page template is default homepage for this sample docs.

It has no sidebar navigation and no sidecode. Page contents is full-width and excerpt acts as a header. We recommend to group pages at first to create nice and usable navigation.

To use landing page just set template property in page config to landing as code example shows.

Global configuration

Global configuration is defined by config.json file which is placed in documentation root directory. This file is mandatory and defines global configuration properties.

These properties are passed to templates which is the main purpose of them.

Default template uses following properties.

Example configuration

./config.json

{
    "title": "META Doc",
    "description": "Project documentation generator with support of HTML and Markdown pages.",
    "keywords": "documentation generator doc api meta readme",
    "meta": {
        "author": "META Platform team"
    },
    "header_title": "<strong>META</strong>Platform <span>Codebase</span>",
    "header_image": "/media/header.jpg",
    "header_image_position": "top",
    "header_github": "https://github.com/metaplatform",
    "header_github_label": "GitHub Page",
    "google_analytics": "UA-12345678-1",
    "menu": [
        {
            "label": "Project homepage",
            "link": "http://www.meta-platform.com/",
            "target": "_blank"
        },
        {
            "label": "Support",
            "link": "http://www.meta-platform.com/contact/"
        }
    ],
    "footer_links": [
        {
            "label": "Support &amp; contact",
            "link": "/meta/#01_Support"
        },
        {
            "label": "Privacy Policy",
            "link": "/meta/#02_Privacy_Policy"
        },
        {
            "label": "Report an issue",
            "link": "https://github.com/metaplatform/meta-doc/issues",
            "target": "_blank"
        },
        {
            "icon": "facebook-box",
            "link": "https://www.facebook.com/",
            "target": "_blank"
        }
    ],
    "base_path": "my-project/my-doc",
    "rewrite_base": "/my-project/my-doc",
    "rewrite": {
        "^beginners-guide/$": "writers-guide/",
        "^contact/$": "support/#contact"
    }
}

General

Property name Type Description
title* string Global page title - HTML <title> tag.
description* string HTML meta description tag contents.
keywords* string HTML meta keywords tag contents.
meta object HTML meta tags in form of key-value.
header_title** string Specifies title in header toolbar.
header_image string Overrides default header toolbar background image URL.
header_image_position string Overrides default header toolbar background image alignment. It is CSS value.
header_github string If set then GitHub button is displayed in header toolbar. Property specifies URL to GitHub profile or repository page.
header_github_label string Overrides default header toolbar GitHub button label.
menu array Specifies header toolbar menu items - see below.
footer_links array Specifies footer menu items - see below.
footer_text string Specifies footer text area contents.
google_analytics string Specifies Google Analytics tracking code. If set then tracking script will be automaticaly printed on each page.
base_path string Base path for links without leading dash - absolute URL path to documentation, required when using 404 page.
rewrite_base string Base path for mod_rewrite. This value is compiled into .htaccess file.
rewrite object Rewrite rules which are compiled into .htaccess and rewrite.json files. See Redirects section for more information.

* recommended

Menu items format

Menu items are specified as an array of item objects. Each item should be defined with following properties.

Property name Type Description
link** string URL of link
label* string Link label
target string Hyperlink target
icon string MDI icon of link - works only for footer_links property.

* recommended
** mandatory

Constants

META Doc compiler rewrites few usefull constants.

Constants can be wrapped:

  • Into double brackets {{name}}
  • Between dollar signs $name$.

Two ways instead of one are provided because of different behaviour of JADE and Markdown languages.

Constant list

{{base}}
{{media}}
{{assets}}
$base$
$media$
$assets$
Name Description
base URL path to generated site root.
media URL path to media directory in generated site.
assets URL path to template assets directory in generated site.

Escaping

If you need to display these constants in your documentation like in this section you have to write ! character after first bracket of after first dolar sign.

Redirects

META Doc comes with second rewrite compiler which generates rewrite rules for apache .htaccess and built-in testing server.

Sample structure

./pages/_404/config.json
            /_excerpt.md
            /content.md

Sample config.json

{
    "icon": "alert-octagon",
    "hidden": true
}

404 Error page

If directory _404 exists in <pages> then this page will be served as 404 response.

Don't forget that _404 is regular page and will be in navigation tree by default.

To correct this behavour you should create config.json file in _404 directory and set property hidden to true.

Documentation skeleton already contains Error 404 page.

Redirect examples

{
    "^beginners-guide/$": "writers-guide/",
    "^contact/$": "support/#contact"
}

Custom redirects

You can specify custom redirect rules in Global configuration file config.json.

Rules are written as an object where key is pattern and value is new URL.

Due to compatibility with .htaccess old and new urls should NOT be starting with slash.

Where to go next?

Usage API Reference