Marfeel Docs

# Cheat Sheet

MarfeelDocs use Github flavoured markup (opens new window), often shortened as GFM, which is the dialect of Markdown that is currently supported for user content on GitHub.com and GitHub Enterprise.

MarfeelDocs also support Extended markdown examples (opens new window).

Here are some basics examples about how to use Markdown, but for more information you can check this Cheatsheet (opens new window) with has more examples. For more complete info, see John Gruber's original spec (opens new window) and the Github-flavored Markdown info pag (opens new window).

# Headers

A MarfeelDocs document should contain at most H1, H2 and H3. To make reading and linking easier, a document requiring deeper levels should be split into several files.

The frontmatter title is what will be visible in the sidebar, while the H1 you define will be visible on top of the document. We recommend that those titles are identical, but the rule of thumb is to keep the frontmatter title short, to fit in the sidebar.

# H1
## H2
### H3

To help readability make sure your documents only have one h1 and that you make good usage of hierarchies.

Links to other markdown files should always contain the .md extension, even if they are deeplinking, like:

[contributing page](./contributing.md)
[external files](./contributing.md#external-files)

This is important for Algolia's crawling of MarfeelDocs.

When deeplinking, replace all spaces by a dash (-) and use only lower-case.

  [I'm an inline-style link](https://www.google.com)
  [I'm an inline-style link with title](https://www.google.com "Google's Homepage")
  [I'm a relative reference to a repository file](../writing-conventions.md)

Output:

I'm an inline-style link (opens new window)

I'm an inline-style link with title (opens new window)

I'm a relative reference to a repository file

Internal links are converted to <router-link> for SPA navigation. Also, every README.md or index.md contained in each sub-directory will automatically be converted into index.html, with corresponding URL /.

Given the following directory structure:

.
├─ README.md
├─ foo
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ README.md
├─ three.md
└─ four.md

Given you are in foo/one.md:

[Home](/) <!-- Sends the user to the root README.md -->
[foo](/foo/) <!-- Sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- Anchors user to a heading in the foo README file -->
[bar - three](../bar/three.md) <!-- You can append .md (recommended) -->

# Emphasis

Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.

Output:

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

# Ordered lists

In this example, leading and trailing spaces are shown with dots: ⋅

1. First ordered list item
2. Another item
3. And another item.

Output:

  1. First ordered list item
  2. Another item
  3. And another item.

# Unordered lists

In this example, leading and trailing spaces are shown with dots: ⋅

* Unordered list can use asterisks
- Or minuses
+ Or pluses

Output:

  • Unordered list can use asterisks
  • Or minuses
  • Or pluses

# GitHub-Style Tables

| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |

Output:

Tables Are Cool
col 3 is right-aligned $1600
col 2 is centered $12
zebra stripes are neat $1
Very large tables are scrollable! Tables Are Cool
col 3 is right-aligned some inline code in tables is also possible
col 2 is centered But no block of code!
zebra stripes are neat You can also use all the emphasis from Markdown, as long as it is all inline.

# Emoji 🎉

A list of all emojis available can be found here (opens new window).

:tada: :100:

Output: 🎉 💯

# Custom Containers default theme

::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is a dangerous warning
:::

::: tip Containers can have titles
This is a tip with a custom title
:::

Output:

TIP

This is a tip

WARNING

This is a warning

WARNING

This is a dangerous warning

Containers can have titles

This is a tip with a custom title

# Syntax Highlighting in Code Blocks

MarfeelDocs uses Prism (opens new window) to highlight language syntax in Markdown code blocks, using coloured text. Prism supports a wide variety of programming languages (opens new window). All you need to do is append a valid language alias to the beginning backticks for the code block:

```js
export default {
    name: 'MyComponent',
    // ...
}
```

Output:

export default {
    name: 'MyComponent',
    // ...
}

```html
<ul>
    <li v-for="todo in todos" :key="todo.id">
        {{ todo.text }}
    </li>
</ul>
```

Output:

<ul>
    <li v-for="todo in todos" :key="todo.id">
        {{ todo.text }}
    </li>
</ul>

# Diagrams

You can use Mermaid to generate diagrams and flow charts from a structured text file. These diagrams can be really helpful to explain how different building blocks of a system interact. The fact that the diagrams are produced in plain text makes the creation process very easy and consistent across developers.

Use the Sequence Diagram format as shown below:

``` mermaid
sequenceDiagram
    participant Anna
    participant Carlos
    Anna->>Juan: Hola Juan, how are you?;
    Juan-->>Anna: Great!;
    Juan->>Carlos: How about you, Carlos?;
    Carlos-->>Juan: Very good!;
```

Output:

sequenceDiagram
    participant Anna
    participant Carlos
    Anna->>Juan: Hola Juan, how are you?;
    Juan-->>Anna: Great!;
    Juan->>Carlos: How about you, Carlos?;
    Carlos-->>Juan: Very good!

TIP

You can use the Mermaid Live Editor (opens new window) to preview the output of your Mermaid sequence diagram.

You can also use a VSCode extension for Mermaid (opens new window)

# Images

To embed an image or screenshot to your document, you must first do the following:

  1. Copy the image or screenshot into your docs/assets folder. Note: The file name must be in lowercase and joined by hyphens e.g. sidebar-example-1.png.

For more information on the file naming conventions, check out the File naming section.

  1. If it is a screenshot, ensure that there are no unnecessary lines or shadows around the screenshot.

       ![Compare & pull request button](./assets/compare-and-pull-request.png)

Output:

Compare & pull request button

The text between [] is the image's alt text. Make sure it is descriptive enough.

For better interoperability and consistency, prefer using images with a png format.

# Images location

Prefer placing all images inside an assets folder, next to the file using the image. Images in articles from external sources will be broken if this convention is not followed.

WARNING

Broken image references break MarfeelDocs build.

If you upload a document with an image, but the shuttle is failing, start by checking all the image paths.

# Grammarly

To avoid typos and guarantee the high level of our documentation, we recommend that you create a free account on Grammarly (opens new window). This writing assistant helps to compose clear, mistake-free writing.

# Linting

You can use the markdownlint extension (opens new window) to lint markdown files in VSCode. Read more about linting in our contributing guide.

← Embed Figma →