Writing for Kirby

Modified: 05 Nov 2024 18:47 UTC

This is a quick introduction to writing documentation and other TritonDataCenter content with Kirby. For a basic template, visit content development template.

Markdown

New content is to be Markdown (Github flavored, except where that's incompatible with Kirby). Existing HTML formatted content should be converted to Markdown as it is reviewed.

Basic Formatting

  1. Never use first-level headers. The first-level head # is reserved for the title of the page. Your top level header should be ##.

  2. Use headers for separating sections of content and not bold text.

Image Markdown

The Kirby way to add an image is with the (image) tag. There are three classes related to image size: full, onehalf, and onethird. For example:

(image: image.jpg alt: Picture of an eagle fishing class: onethird)

which results in

Picture of an eagle fishing

Important: Please only use images that are included in the current page content folder. This may occasionally result in duplicating an image from another page, but that's better than having images break on reorganization.

Always include alt text for accessibility.

Learn more about image file rules below.

Although the official markdown way to include links works on our sites, it's better practice to use the official Kirby method to include links. The following appears as tritondatacenter.com.

(link: http://www.tritondatacenter.com)

This makes it easy to add both custom text, CSS classes, and popups. The following list includes the links side-by-side with the generation code.

Example Markdown
tritondatacenter.com (link: http://www.tritondatacenter.com)
TritonDataCenter's website (link: http://www.tritondatacenter.com text: TritonDataCenter's website)
Popup for TritonDataCenter's website (link: http://www.tritondatacenter.com text: TritonDataCenter's website popup: yes)
TritonDataCenter's website (link: http://www.tritondatacenter.com text: TritonDataCenter's website class: website-class)
info@tritondatacenter.com (email: info@tritondatacenter.com)

When linking within our site, use relative links so that they won't break when moving domains or testing the site locally. For example, (link: /private-cloud/packages/configuring). That will link directly to Configuring Triton packages.com.

If linking to content from tritondatacenter.com within docs.tritondatacenter.com documentation, you must include the full URL, i.e. (link: https://tritondatacenter.com/blog/nodejs-9-release-summary).

Video Markdown

Video is uploaded to TritonDataCenter's Vimeo account and included via the following markdown:

(vimeo: //vimeo.com/<video-id>)

If your blog post features a video, always include a thumbnail.jpg at 16x9 ratio in the directory.

To add a video gallery to your blog post, include the following section:

----
vidgallery:
-
    video: (vimeo: //vimeo.com/<video-id>)
    thumb: gallery-<video-id>.jpg
-
    video: (vimeo: //vimeo.com/<video-id>)
    thumb: gallery-<video-id>.jpg
-
    video: (vimeo: //vimeo.com/<video-id>)
    thumb: gallery-<video-id>.jpg

You can then insert this gallery anywhere in the text section with the kirby tag (vidgallery: ). This tag doesn't take additional arguments at this time.

Code

Whenever possible, blocks of code should be included as text, wrapped with backticks and a code highlighting hint. Images should not be used.

  ```
  This is a GitHub code fence.
  ```

Right now you can use any of the following language specifiers with your backticks:

If you don't specify anything, the code block is left alone. You can also use the specifier prettyprint and the highlighter will take its best guess.

Variables

Here are some common variables for code examples.

Tables

This is how to create a table:

| Term  | Meaning |
| :----  | :----    |
| ANY     | Any machine anywhere on the Internet |
| ALL VMS | All instances on this data center that have the Cloud Firewall feature enabled. |

The colons specify the alignment of the headings. It will come out looking like this:

Term Meaning
ANY Any machine anywhere on the Internet
ALL VMS All instances on this data center that have the Cloud Firewall feature enabled.

If you use Sublime Text, there's a package you can use to help you create and edit tables.

Files and folders

Layout

The main thing to keep in mind about Kirby is this: one HTML document = one directory

This is an example of part of our directory-style for the documentation site:

content
├── 10-public-cloud
│   ├── 10-getting-started
│   │   ├── 50-limits
│   │   │   ├── customer-portal-limits-message.png
│   │   │   └── index.md
│   │   └── index.md
│   ├── 20-instances
│   │   └── index.md
│   ├── 30-api-access
│   │   └── index.md
│   ├── 60-tags
│   │   ├── tag-names.png
│   │   └── index.md
│   └── index.md
├── 20-private-cloud
│   ├── 20-install
│   │   └── index.md
│   └── index.md
├── error
│   └── error.md
├── home
│   └── home.md
├── search
│   └── search.md
└── site.md

File and folder naming conventions

All file and folder names should be in lowercase, separating words with hyphens. Exceptions: files that are expected in upper case, like Dockerfile or CONTRIBUTING.md (these are typically not content files).

Image Files

Compress your images before adding them to the repository. Images should be included within the same directory as the content.

If the image is the main thumbnail for the page or post, it should be named thumbnail.jpg. If it is part of a gallery, the image should be named gallery-<descriptor>.jpg. Otherwise, the name should be descriptive, instead of a random series of numbers such as 10237929.jpg.

Unless the image requires transparency, always use JPG images.

Template style

Documentation

Here is a sample of the structure of a basic documentation page:

Title: <name of the page, as seen in navigation and at the top of the page>
----
Fulltitle: <Optional, this replaces the title at the top of the page and in the title tag, but not the navigation.>
----
Text:
<Body content goes here.>
```
All new files should be labeled `index.md`.

Redirect section

There are two types of redirects: 301 and canonical. A 301 redirect tells search engines that the page has been permanently removed and to pass credit to the new page.

To add a 301 redirect to a blog post, add this section directly below the "title":

----
Redirect: <full URL for redirect>

A canonical redirect tells search engines that there are multiple versions of the page/content and to only index the version indicated. The others will remain available for people to see, but the index and credit should be given to the preferred URL.

For canonical redirects:

----
Canonical: <full URL for redirect>