Skip to content

Latest commit

 

History

History
257 lines (190 loc) · 9.32 KB

AUTHORING.md

File metadata and controls

257 lines (190 loc) · 9.32 KB
Raw

Content Author Guide

This document is a guide for adding content to the spine.io site.

Table of Contents

Table of contents generated with markdown-toc

Using URLs in Markdown

Links to Blog Posts

There are thee rules to follow:

Rule 1 -- Always concatenate Jekyll and Liquid tags

Good Bad
href="{{ site.baseurl }}{{ post.url }}" href="{{ site.baseurl }}/{{ post.url }}"

This removes the double-slash from your site's URLs.

Rule 2 -- (Almost) Always start links with {{ site.baseurl }}

Good Bad
href="{{ site.baseurl }}{{ post.url }}" href="{{ post.url }}"

This fixes almost all of the in-site links. The next rule covers the remainder.

Exception: Start hyperlinks with {{ site.url }}{{ site.baseurl }} in feed pages, like atom.xml.

Rule 3 -- Always use a trailing slash after {{ site.baseurl }}

Good Bad
href="{{ site.baseurl }}/" title="Home" href="{{ site.baseurl }}" title="Home"
Good Bad
href="{{ site.baseurl }}/public/favicon.ico" href="{{ site.baseurl }}public/favicon.ico"

Visit Configuring Jekyll for Project GitHub Pages and for User GitHub Pages if you want to know why these rules should be followed.

URL rules

All these URLs lead to the same page: /docs, /docs/, /docs/index, /docs/index.html. But if you use them all throughout the site, it will create problems for search crawlers.

Please stick to these rules for using links on the site.

Use a trailing slash to refer to the directory containing the index.html file

Good Bad
{{ site.baseurl }}/docs/introduction/ {{ site.baseurl }}/docs/introduction/index

Drop the .html suffix. This will simplify the URL

Good Bad
{{ site.baseurl }}/docs/introduction/rules {{ site.baseurl }}/docs/introduction/rules.html

Adding collapsible list for sidebar navigation

For collapsible categories we use the Bootstrap Collapse component.

For instructions on adding or changing sidebar navigation, please see the Navigation Author Guide.

Adding code samples to the site

Please see this document for the instructions.

Testing broken links

We use the html-proofer tool to test broken links. To start test locally you may be required to install the Gem of the tool first:

bundle install

... and then build the site:

jekyll build

After that, please use the following command:

./_script/proof-links

We only log errors falling within the 4xx status code range. Please note that links to GitHub are ignored by --http-status-ignore "429" command, because GitHub rejects the check coming from htmlproofer. Details of this are described in this issue.

Also, we have a GitHub Action which tests the links when the pull request is created to the master. Please see the .github/workflows/proof-links.yml file for details.

Adding email links

We use the Jekyll Email Protect to protect our email addresses from spam bots. We store all email variables in the _data/support.yml file.

In HTML

<a href="mailto:{{ 'example@example.com' | encode_email }}">{{ 'example@example.com' | html_encode_email }}</a>

Or through a variable:

<a href="mailto:{{ site.data.support.email | encode_email }}">{{ site.data.support.email | html_encode_email }}</a>

The above code will yield:

<a href="%65%78%61%6D%70%6C%65@%65%78%61%6D%70%6C%65.%63%6F%6D">%65%78%61%6D%70%6C%65@%65%78%61%6D%70%6C%65.%63%6F%6D</a>

In Markdown

In markdown files we cannot obfuscate the link text, so it would be safer to use something like Contact us.

[{{ Contact us }}](mailto:{{ site.data.support.email | encode_email }})

The above code will yield:

<a href="%65%78%61%6D%70%6C%65@%65%78%61%6D%70%6C%65.%63%6F%6D">Contact us</a>

Managing the “Prev”/“Next” buttons in the documentation

The “Prev”/“Next” buttons are generated automatically for all document pages. The generation is based on the doc_side_nav.yml navigation.

To customize the automatically added “Prev”/“Next” buttons, add the appropriate variables to the front matter block of the document page.

To hide the “Previous” or “Next” button:

prev_btn: false

next_btn: false

To customize the “Previous” or “Next” button name:

prev_btn: 
  page: Development Process Overview

next_btn: 
  page: Development Process Overview

To customize the “Previous” or “Next” button name and URL:

prev_btn: 
  page: Development Process Overview
  url: /docs/introduction/

next_btn: 
  page: Architecture Overview
  url: /docs/introduction/architecture.html

Related files:

  • _includes/doc-next-prev-nav.html - the navigation template with the automatic button generation;
  • _sass/modules/_doc-next-prev-nav.scss - navigation styles;
  • _layouts/docs.html - the documentation layout where the doc-next-prev-nav is included.

Using a language switcher for source code samples

The switch state will be saved globally so that the user can navigate between pages.

Usage

To show language tabs use the structure below. Add a lang attribute with Java, Kotlin, JavaScript or any other language value for divs with content. If no language is provided, the content will not be displayed.

<div class="code-tabs">
    <div class="code-tab-content" lang="Java">
         Any Java content here
    </div>
    <div class="code-tab-content" lang="Kotlin">
         Any Kotlin content here
    </div>
    <div class="code-tab-content" lang="JavaScript">
         Any JavaScript content here
    </div>
</div>

In markdown, all tags should be left-aligned. This way, the blocks of code will not be broken:

<div class="code-tabs">
<div class="code-tab-content" lang="Java">
Any Java content here
</div>
<div class="code-tab-content" lang="Kotlin">
Any Kotlin content here
</div>
<div class="code-tab-content" lang="JavaScript">
Any JavaScript content here
</div>
</div>

If you don't need to display the tabs, but only need to show a specific paragraph of text or change the title depending on the language, just use this:

<div class="code-tab-content" lang="Java">
# Getting started with Spine in Java
</div>

<div class="code-tab-content" lang="Kotlin">
# Getting started with Spine in Kotlin
</div>

To change only some of the words in a sentence, use the <span> tag with the .inline class:

A minimal client-server application in
<span class="code-tab-content inline" lang="Java">Java</span>
<span class="code-tab-content inline" lang="Kotlin">Kotlin</span>
which handles one command to print some text...

Related files

The files are stored in the documentation repository.

  • _sass/base/_code-tabs.scss - styles for the code tabs;
  • tools/code-tabs.js - code tab implementation.