Marfeel Docs

# Writing conventions

MarfeelDocs follows several writing conventions to maintain consistency across all the platform. Find them explained in detail in this article.

# File Extension

Always use .md file extension for files with GitHub Flavored Markdown.

# File Naming

Always use spinal-case (opens new window) (also called kebab-case or hyphen-separated (opens new window) for file names and use snake_case (opens new window) only if it contributes to a better understanding of the content.

File:

  • how-to-use-layouts.md

or

Folder:

  • how-to-use-layouts
  • how-to-use-layouts/index.md
  • how-to-use-layouts/how-to-use-layouts.png

The .md title or the folder title gets turned into the URL route automatically.

Article titles should be short and reflect the main theme of the article to help readers quickly find relevant info. Many people use a search engine to find topics like "Marfeel layouts", so the article title should ideally reflect common search terms.

The folder name is used in the URL, so only use dashes -, numbers 0-9, and lowercase letters a-z for it.

# Frontmatter

YAML frontmatter (opens new window) is supported out of the box. All files by default have title and tags

---
title: How to use Whitecollar
tags: guide
---

This data will be available to the rest of the page, along with all custom and theming components and all of them have different usages.

  • title: used as H1 title

# Tags

In the Frontmatter section, you need to create your document tags. Tags are important as they are used to classify documents and improve the search functionality. The tags that should be used are the following:

  • tags: used for search and content discovery. We use tags at the start of each document. The following tags can be used:
    • seo
    • alarm
    • guide
    • performance
    • trd (Technical Requirements Document)
    • prd (Product Requirements Document)
    • council (Technical Council)
    • docs (If the document cannot fit into any of the above categories)

# Scope

Depending who the document is targeted to it will have one of the following scopes:

  • scope:

    • public: This documentation is public and will be accessible publicly inside and outside Marfeel.

    • internal: Internal docs are meant to be documentation oriented to developers, explaining the insights of the Marfeel platform, its exposed APIs, how to debug certain parts of the code... This documentation is for Marfeelers only and becomes accessible once you've logged in the MarfeelDocs platform.

---
title: How to do a WhiteCollar
scope: public | internal
---

Default scope

Any document without a scope is considered internal by default to avoid making information public by error.

WARNING

MarfeelDocs is currently entirely public, independently of the scope given in frontmatter.

← Cheat Sheet →