Skip to content

Formatting

Jump to bottom
alaric-datamesh edited this page Mar 29, 2018 · 23 revisions

Every docs page follows the same pattern. Although fairly straight forward, a little care should be taken to ensure consistency across pages.

Page creation (CLI)

Hugo allows for page creation, using pre-set archetypes to provide a base for templates. This is the preferred method.

To create, use the following pattern:

hugo new <folderdestination>/<pagename>.md

Example

hugo new concepts/snapshots.md

Page creation (text editor)

You can also create new pages in a text editor by copy and pasting front matter from another pre-existing page, and changing the front-matter. This isn't ideal, but will work just fine.

Front-matter

title

The title of the page. Be brief and to the point, as this is used in menus

synopsis

Introduce content and provide a quick snapshot of what the page is about. Aim for around 120 characters.

knowledgelevel

By defining complexity of content, you provide a check method for different user groups to engage with the content. Choose from

  • Beginner
  • Intermediate
  • Advanced
  • Expert

parent

If this is a child page, you must define it's parent. The parent is the folder the item belongs to.

Example.

[menu]
  [menu.main]
    parent = "concepts"

Shortcodes

Shortcodes are used to inject rich media into markdown. See below for use cases and examples.

Videos

Any video from youtube or vimeo can be easily embedded in markdown by adding the ID (found in the url) to the shortcode

Example (where xxx is the video ID)

{{< youtube xxx >}}
{{< vimeo xxx >}}

Images, with optional caption and link

A figure is used when you wish to add a caption with an image. The shortcode takes two variables, the image URL and the caption itself. If you don't need a caption, simply leave the title blank.

Example

{{< figure src="http://www.fillmurray.com/1600/1200" title="Look it's Bill Murray everybody" link="/<somepage>" >}}

You can refer to images in docs repo with a src like so:

{{< figure src="blog/deep-dive-dotmesh/images/Dotmesh briefing deck - Jan 18-page-002.jpg" >}}

...for an image file in hugo/content/blog/deep-dive-dotmesh/images/Dotmesh\ briefing\ deck\ -\ Jan\ 18-page-002.jpg.

Code

You can add codeblocks using git code fence syntax. Be sure to define the language type.

Hugo code-fences from the documentation

Code added manually

If you want to side-step Hugo's syntax highlighting and go it alone, then the following HTML provides an example of how to do so. I must stress, generally don't do this without good reason.

Note that the <div class="highlight"> must wrap around the whole block and the <pre> must have a class of <pre class="chromaManual">.

<div class="highlight">
<pre class="chromaManual">$ <kbd>kubectl examine secret dotmesh -n dotmesh -o yaml</kbd>
apiVersion: v1
data:
  dotmesh-admin-password.txt: Y29ycmVjdGhvcnNlYmF0dGVyeXN0YXBsZQo=
  dotmesh-api-key.txt: <em>VlZLR1lDQzNHNEs1RzJRTTNHTElWVEVDVlNCV1dKWkQK</em>
kind: Secret
metadata:
  creationTimestamp: 2018-01-17T15:03:11Z
  name: dotmesh
  namespace: dotmesh
  resourceVersion: "418"
  selfLink: /api/v1/namespaces/dotmesh/secrets/dotmesh
  uid: 88c31d8b-fb97-11e7-b1fe-0242cd52be10
type: Opaque
$ <kbd>echo VlZLR1lDQzNHNEs1RzJRTTNHTElWVEVDVlNCV1dKWkQK | base64 -d</kbd>
<em>VVKGYCC3G4K5G2QM3GLIVTECVSBWWJZD</em>
</pre>
</div>

Overviews

When adding an overview, you should add it to the start of the page's markdown content to help introduce a user to core ideas or pre-requisites.

Please add in list format (ordered or unordered). Links and text styling are OK

Example

{{% overview %}}
1. A sound understanding of git flows
2. [Kubernetes](https://www.kubernetes.com) & [Docker](https://www.docker.com) installed in place xyz.
3. Patience and coffee
{{% /overview %}}
Clone this wiki locally