Skip to content

Latest commit

 

History

History
280 lines (198 loc) · 8.62 KB

AUTHORING.md

File metadata and controls

280 lines (198 loc) · 8.62 KB

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

To refer to another page, image, or asset in the Spine documentation, use relative URLs. The site domain and documentation version are added automatically.

URLs in markdown

There are two rules to follow:

Rule 1 -- All internal links must not start with a slash.

Good Bad
[Introduction](docs/introduction/) [Introduction](/docs/introduction/)

Rule 2 -- Each link should end with a slash to prevent unnecessary redirects.

Good Bad
[Introduction](docs/introduction/) [Introduction](/docs/introduction)

Variables

This example shows how to use data variables and a version variable in a URL:

[Hello World]({{% get-site-data "repositories.examples" %}}/hello/)

[Introduction](docs/{{% version %}}/)

Will be rendered as:

<a href="https://github.com/spine-examples/hello/" target="_blank">Hello World</a>

<a href="/docs/1.9.0/">Introduction</a>

Where:

  • {{% get-site-data "repositories.core_jvm_repo" %}} will apply the core_jvm_repo from the site-commons -> data/repositories.yml file.
  • {{% version %}} adds the version label of the current page -> 1.9.0.

Images

To render an image in markdown use:

![Image alt](img/articles/test.webp)

Use anchors to specify image size: #medium, #small:

![Image alt](img/articles/test.webp#medium)`

URLs in HTML

When working with layout partials, URLs should be specified using the following syntax:

<a href="{{ `docs/guides/requirements` | relURL }}">Requirements</a>
<img class="logo" src="{{ `img/spine-logo.svg` | relURL }}" alt="Spine logo">

Markdown pages

It is nice to have the following parameters on every markdown page, especially in documentation:

---
title: Getting Started in Java
description: This guide shows how to start working with Spine in Java.
headline: Documentation
---

Where:

  • title page title.
  • description a short summary of what this page is about. Used for SEO.
  • headline shown under the main navigation. If omitted, it is not rendered.

Optional parameters:

---
header_type: fixed-header
body_class: privacy
customjs: js/pages/privacy.js
---

Where:

  • header_type controls how the page header behaves (for example, stays fixed while scrolling).
  • body_class adds a CSS class to style a specific page. By default, the body class is based on the page type.
  • customjs loads page-specific JavaScript.

Navigation

Main navigation

To edit navigation items, modify site/data/navbar.yml. The navigation layout template is located at site/layouts/_partials/components/navbar/navigation.html.

Documentation side navigation

The documentation side navigation can be edited in the SpineEventEngine/documentation repository in the docs/data/docs/<version_id>/sidenav.yml file.

If it is part of a specific documentation module, it can be found in the corresponding repository at docs/data/docs/<module>/<version_id>/sidenav.yml.

Documentation “Next/Prev” buttons

The “Prev”/“Next” buttons are generated automatically for all document pages based on the sidenav.yml. The implementation is inside the SpineEventEngine/site-commons.

Adding code samples to the site

Please see this document for the instructions.

Testing broken links

We use the Lychee tool to test broken links. To start test locally you may be required to install the tool.

Then navigate to the site directory and run the site locally

hugo server

Make sure it runs on port 1313.

To test broken links, run following command from the root of the project:

./_script/proof-links

We only log errors falling within the 4xx status code range. Please note that some of the links are added to excludes in the lychee.toml file.

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

Cloak email

The cloakemail shortcode is used to cloak emails or phone numbers from spamming bots. We store all email variables in the site/data/emails.yml file in the site-commons.

In markdown files, use the shortcode with a provided variable from a data file, for example:

{{< cloakemail address_variable="emails.sales_email" >}}

or with the display text:

{{< cloakemail address_variable="emails.sales_email" display="Contact us" >}}

Note blocks

To add a note block with additional styles in markdown files, use the predefined note-block shortcode.

{{% note-block class="note" %}}
This is some dummy text to show how a note block can look. Check this 
[example link to guides][test-url] to see how links appear inside the block.

You can add more lines or even lists:
- First item.
- Second item.
{{% /note-block %}}

[test-url]: docs/guides/

You can use only predefined classes such as: note, warning, or lead.

{{% note-block class="lead" %}}
The test lead block.
{{% /note-block %}}

Code blocks

There are two ways to add code blocks with syntax highlighting.

1. With triple backticks

Please always specify the language syntax to avoid problems with the layout.

```bash
git clone git@github.com:spine-examples/hello.git
```

You can configure the appearance of Hugo code blocks using parameters, as described in the official documentation:

  • linenos=table – configures line numbers and renders them in a table view. The table view is necessary for correct copying of code.
  • hl_lines=[8,"15-17"] – lists a set of line numbers or line number ranges to be additionally highlighted.
  • linenostart=199 – starts the line number count from 199.
```java {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```

2. Using highlight shortcode"

The highlight shortcode allows to set custom visibility options related to this project, such as custom CSS classes, the text highlighting on the selected line, a file name bar, etc.

{{< highlight lang="java" params="hl_lines=10 19, linenos=table" class="hl-text-only" >}}
@BeforeEach
void sendCommand() {
...
}
{{< /highlight >}}

Where:

  • lang – the language syntax. See the supported languages.
  • params – optional standard Hugo highlighting parameters as a string.
  • file – an optional name of the code file to display on the code header panel.
  • class – an optional class name that the code block will be wrapped in.

The class hl-text-only is predefined and used to highlight only the text without highlighting the entire line with background.