Style, syntax, formatting, and general rules

Edit on GitHub

This document describes the sructure, main style, syntax and formatting rules of the Spryker documents.

Directory structure

The main directory for holding all the documents is docs at the root of the project. The second layer is product directories: marketplace, scos, cloud, etc. Under each product directory, there are realm directories: user and dev. Each of these directories contains category directories with optional sub-categories. Category or sub-category directories contain documents. Some categories are versioned to reflect differences for various releases, so each version of the sub-category is located in a separate folder, for example, see Features. For more details on versioning pages, see Working with versions.

directory structure

Creating documents and categories

We use Markdown (.md) to write documents. All documents reside in the docs directory. See Directory structure for details on how this directory is organized. You can use any text editor such as VSCode or Atom for creating the files in Markdown. For information about specific Markdown syntax for documentation, see Markdown syntax.

You can create new pages in any documentation category or sub-category under the realm directories (user, dev). You can also create directories for new categories under the realm directories.

For example, to create a new sample-category category and a foo-bar page under it for a Marketplace business user, you create a new directory called sample-category under /docs/marketplace/user. After that, create the file foo-bar.md in that directory. Thus, the path to your new page would be: /docs/marketplace/user/sample-category/foo-bar.md.

Warning

Currently, the maximum nesting level in the documentation categories is 3. This means that for each category you can have only one sub-category. For example, marketplace/user/features/202108.0/merchant/, where features is the category (first level of nesting), 202108.0 is the version (does not affect the level of nesting) merchant is the sub-category (second level of nesting). The third level of nesting are the .md files under the sub-category.

Info

You can use any valid URL characters in the names of your document files or category directories. It is strongly recommended to use dashes (-) instead of underscores (_) in the names because these names will eventually be mapped to URLs, and underscores have a negative impact when it comes to SEO.

Templates

To keep our docs consistent, we have templates for all types of documents. The templates are stored in the _templates directory. Therefore, every time you need to create a new document, pick the right template from this folder, copy it to your new page, and write the document based on the structure of the template and instructions therein.

TEMPLATE DESCRIPTION
back-office-user-guide-template Use this template for creating Back Office user guides or Merchant Portal user guides.
concept-topic-template Use this template for creating general and technical conceptual topics, such as feature overviews or technical articles.
feature-walkthrough-template Use this template for creating feature walkthrough guides.
feature-integration-guide-template Use this template while working on the integration guides. Check the instructions on formatting for the integration guides.
glue-api-storefront-guide-template Use this template for creating Glue API guides.
data-export-template Use this template for creating documents on data export.
data-import-template Use this template for creating documents on data import.
module-migration-guide-template Use this template for creating module migration guides.
troubleshooting-guide-template Use this template for creating troubleshooting pages.
howto-guide-template Use this template for creating howto guides.
best-practices-file-template Use this template for creating best practices docs.
Warning

Make sure that the front matter of your document contains the name of the template.

Front matter

Every document must have a YAML front matter block. This block consists of key-value pairs delimited by 3 dashes from each side and must come before any content in the document. The supported parameters on our documentation website are:

---
title: Foo bar document
description: Exemplary description text.
last_updated: Dec 09, 2021
template: concept-topic-template
tags: [new, B2B, B2C]
redirect_from:
	-/docs/cloud/dev/spryker-cloud-commerce-os/troubleshooting.html
	-/docs/marketplace/dev/feature-integration-guides/202108.0/combined-product-offer-import-integration.html
related:
	- title: How to extend an existing Gui table
		link: docs/marketplace/dev/howtos/how-to-extend-gui-table.html
  - title: Sales Data Export feature integration
    link: docs/scos/dev/feature-integration-guides/page.version/sales-data-export-feature-integration.html
---
FRONT MATTER PARAMETER DESCRIPTION FORMAT WITH EXPLANATION EXAMPLE REQUIRED?
title The name of the document. Text. Keep in mind, that if you have special characters in title like column or apostrophe, the title should be in single quotes.
  • Creating product lists
  • ‘HowTo: Force HTTPS’
description Short description of what this page is about. Sentence. Learn how to use the front matter.
last_updated Last updated date of the page to be displayed on the website. Date in the format: Mon-DD-YYYY (month abbreviation, day with leading zeros, year) Jun 16, 2021
template Template based on which the page was created. Name of the template from Github repository without the extension of the file (.md). feature-integration-guide-template
tags Tag names. The name of the tag in brackets. [B2B], [B2C]
redirect_from Allows setting up redirects for pages whose location changes or pages that are completely deleted from the documentation. To set up a redirect, press the tab button and enter the path starting with /docs and containing the exact version, if the document is versioned. - /path/to/a/file.html -/docs/cloud/dev/spryker-cloud-commerce-os/troubleshooting.html
related Shows the list of articles related to the page you are on. To add a related article, press the tab button and enter the name of the article in the title parameter and the link to the file in the link parameter. Mind the link parameter: no dash before link, no slash before docs. Always use page.version in the link for related articles, even for unversioned articles! - title: Title of the related page
link: path/to/a/file.html

For more information about front matter, see the Jekyll’s official website.

Adding documents to the navigation

Once you created a new document, you must add to the sidebar navigation. Keep in mind that a path to a document file will be fully mapped to an URL of that document except that .md extension will be replaced with .html. This means that the document from the example above can be accessed in the browser with zero configuration by visiting http://localhost:4000/docs/marketplace/user/sample-category/foo-bar.html.

Each product/realm set has its own sidebar, which is represented by a YAML file in the _data/sidebar directory. The sidebar name is {product}_{realm}_sidebar.yml. So, for example, for the Marketplace user documentation, the sidebar file is called marketplace_user_sidebar.html. The sidebar consists of the list of files files that are present in the navigation. As a best practice, as soon as you create a new page, add it to your sidebar (so you don’t forget about the page).

- product: SCOS
  nested:
  - title: Sample category
    nested:
    - title: Intro to Spryker
      url: /docs/scos/user/sample-category/foo-bar.html
  • The product key represents the top level category for the sidebar. It is entered once at the top of the sidebar.
  • The nested key describes the nested items of the category—pages or sub-categories.
  • The first title key sets the category name as it will be displayed in the sidebar.
  • The second title key in this example sets the page title.
  • The url key must specify the absolute URL to the document page.

Creating landing pages for the main categories

For each main category, like Setup, Feature integration guides, HowTos, etc., you can create the index.md. file. This lets you open category pages without specific files in the link. For example, let’s do that for the Glue API guides section of the developer guide:

  1. In docs/marketplace/dev/glue-api-guides, add the index.md file. Make sure you specify the title in the file.

  2. In the marketplace_dev_sidebar.yml file, add URL for the Glue API guides element. You don’t have to write index.html in the end of the link, the link will work without it:

- title: Glue API guides         
  url: /docs/marketplace/dev/glue-api-guides/
  1. Save the changes.

If you now open the Glue API guides category, your page looks like this:

img

Working with versions

We have two types of versions: page versions and the global website version.

The versions are managed in the config.yml file*.

Page version

The page version is the version of the current page. Therefore, page versions apply to the versioned pages only. The page versions reside in the version-related scopes section of the config.yml file:

config yaml

To add a new version for the versioned categories:

  1. In the config.yml file, version-related scopes section add the version with the scope and values parameters as shown in the picture above.
  2. In the main categories for which the version you added should exist, create the folder named as the version value from the previous step. For example, if you created version 202221.0 in config.yml -> version-related scopes, the folder should also be called 202221.0.
  3. Add the file that should be in the new version, to the folder:

files list

You can make a reference to the currently opened version of the versioned page using the {{page.version}} variable in text and in links. For example, if you open a document in version 202108.0 in the editor and write there:

This feature requires version  of the Merchants feature.
For details on the feature, see [Merchant feature overview](/docs/marketplace/user/features/{{page.version}}/merchants/merchants-feature-overview.html).

on the website, your text will look like this:

This feature requires version 202108.0 of the Merchants feature.
For details on the feature, see Merchant feature overview(link to merchants-feature-overview.html version 202108.0).
Info

You can use the {{page.version}} variable only when you refer to versioned pages on versioned pages. To make a reference to the latest page version on a versioned page to an unversioned page, use the {{site.version}} variable described in the next section. To make a reference on an unversioned page to an unversioned page, do not use any variable.

Global site version

The global version is the main website version. Usually, we make the version of the latest release the main website version. The global version is applied to both versioned and unversioned pages. It is specified in the first line of the config.yml file:

img

To make a reference to the main (last) website version on either versioned or unversioned pages, use the {{site.version}}. For example, if the main version of your website is 2020109.0, if you write

For details on the feature, see [Merchant feature overview](/docs/marketplace/user/features/{{site.version}}/merchants/merchants-feature-overview.html).

the Merchant feature overview link will take the user to the Merchant feature overview article in version 2020109.0.

Deleting pages

If you happen to delete the unnecessary or outdated page from the website, make sure to set up a redirect for it. See Front matter to learn how to set up redirects.

Troubleshooting

This section contains most coming issues that you may face while working with docs and expected ways how to resolve the problem.

Filename too long in Git for Windows

If you face the “Filename too long” error, or an error like this one “spryker.github.io/vendor/bundle/ruby/2.7.0/gems/jekyll-4.2.0/lib/jekyll/convertible.rb:222:in `write’: No such file or directory @ rb_sysopen - E:/Jekyll/spryker.github.io/_site/docs/scos/dev/tutorials-and-howtos/introduction-tutorials/tutorial-content-and-search-attribute-cart-based-catalog-personalization-spryker-commerce-os/tutorial-content-and-search-attribute-cart-based-catalog-personalization.html (Errno::ENOENT)”, run the following command to circumvent it:

git config --system core.longpaths true

This command only solves the problem by being specific to the current project.

Escaping Liquid template tags

Jekyll supports a Liquid templating system. All features can be found on page Liquid.

Beware that Liquid syntax uses the same tags as Twig. To prevent Twig tags processing use * //Twig template *

In case, your page requires a Twig code sample to be inserted, enter the above-mentioned placeholder in the beginning and at the end of the code sample. Example:

liquid syntax

To get rid of the extra lines in the code sample, use code sample placeholder.