Contributing

We are not taking public contributions at the moment, but will soon begin accepting pull requests. For now, if you encounter an error or spot something that is missing on this documentation portal, please create an issue

Creating a new article

Follow these guidelines to create a new article:

1. Create the article on both en-us and pt-br projects with encoding UTF-8 BOM
2. Alter the toc.md from both projects including the article

Tip

An easy way to ensure that the new article has UTF-8 BOM encoding is to copy an existing article instead of creating a new file.

You don't need to write both versions of the article right away, you can write one of the versions and put this on the other one:

# Article title

<!-- link to version in Portuguese -->
<div data-alt-locales="pt-br"></div>

or

# Título do Artigo

<!-- link to version in English -->
<div data-alt-locales="en-us"></div>

Authoring documentation

Here are the most important links about how to author documentation:

• Mastering Markdown - GitHub Guides
• DocFX Flavored Markdown - DocFX website
• Links and Cross References - DocFX website
• Overwrite Files - DocFX website

Markdown cheatsheet

Here are sintaxes for the most common elements:

• Headers
• Bold
• Italic
• Inline code
• Lists
• Horizontal rulers
• Links
• Code snippets
• Includes
• Include code snippets
• Images
• Blockquotes, notes and warnings
• Tables

Headers

Top level (H1) header:

# Article title

Level 2 (H2) header:

## Section title

Level 3 (H3) header:

### Subsection title

Bold

This is a **bold** statement

This is a bold statement

Italic

This is a *foreign word*.

This is a foreign word.

Inline code

Pass the `callback` parameter

Pass the callback parameter

Lists

Unordered:

* Item A
* Item B
  * Subitem (prefix spaces to align with parent)
    * And so on
* Item C

• Item A
• Item B
  • Subitem (prefix spaces to align with parent)
    • And so on
• Item C

Ordered:

1. Item 1
1. Item 2
   1. Subitem (prefix spaces to align with parent)
      1. And so on
1. Item 3

1. Item 1
2. Item 2
   1. Subitem (prefix spaces to align with parent)
      1. And so on
3. Item 3

The actual numbering does not matter, DocFX will order the list when rendering the file. Prefer repeating 1. on every item instead of writing 1., 2., 3. etc because this allows for easy reodering of items.

Horizontal rulers

Use *** to insert a horizontal ruler:

Something

***

Some other thing

Note

Do not use the syntax ---, as it has a special meaning on DocFX

Links

[text](url)

To articles on same folder:

See the article [Welcome](index.md)

See the article Welcome

To articles on other folders:

You can use the [Lacuna PKI SDK](../pki-sdk/index.md) for this purpose

You can use the Lacuna PKI SDK for this purpose

To classes:

See class @Lacuna.RestPki.Client.RestPkiClient

See class RestPkiClient

To methods:

See method @Lacuna.RestPki.Client.RestPkiClient.GetPkiBrazilTimestamper

See method GetPkiBrazilTimestamper()

To find out the exact UIDs of classes and methods, see .yml files on folder api after building the docfx project.

In some cases, the syntax @uid does not work for cross referencing. In such cases, use:

<xref:Lacuna.RestPki.Client.RestPkiClient>

If the uid contains a #, encode it as %23:

<xref:Lacuna.Pki.LinkedTrustArbitrator.%23ctor(Lacuna.Pki.ITrustArbitrator[])>

Links to article sections:

First, you need to declare the anchor name right before the section header:

<a name="anchor-name" />
## Section title

Note

If the article is in English and the section title matches the anchor name (transformed to lowercase and replacing spaces with hyphens), you don't need to declare the anchor

Then, to link to the section:

See [Default error callback](../web-pki/advanced.md#default-error-callback)

See Default error callback

Code snippets

```languageid
code
```

Common language IDs:

• csharp or cs
• javascript or js
• html

Code snippets can be indented with lists:

1. Installation

   1. Set things up

   2. Run this:

      sudo apt install something
      

   3. Finish things up

2. Done

See all supported Language names and aliases.

Includes

[!include[Title](url)]

Include blocks common to both languages are kept on the includes/ folder. For instance, to include the rest-pki-samples-matrix.md block from a location such as docs.en-us/articles/project-name/article.md:

[!include[Rest PKI samples matrix](../../../includes/rest-pki-samples-matrix.md)]

Example: Rest PKI

Include code snippets

• Syntax
• Example: CadesSignatureCompression [src]

Images

![Alt Text](url)

url can be a remote URL, but is usually a relative reference to an image on the images/ folder.

For instance, to reference the image images/pki-sdk/pades-rectangle.png from the following locations:

From docs.en-us/articles/project-name/article.md:

![Image name](../../../images/pki-sdk/pades-rectangle.png)

From docs.en-us/articles/project-name/subfolder/article.md:

![Image name](../../../../images/pki-sdk/pades-rectangle.png)

Samples:

• PKI SDK / Get started / Adding the nuget package
• Web PKI / Browser support

Blockquotes, notes and warnings

Blockquotes:

As Jeffrey Lebowski once said:

> Far out.

As Jeffrey Lebowski once said:

Far out.

Notes:

> [!NOTE]
> This is an important notice

Note

This is an important notice

Warnings:

> [!WARNING]
> Watch out!

Warning

Watch out!

Also supported:

Tip

This is a tip

Important

This is important

Caution

Proceed with caution

Tables

First Header                | Second Header
--------------------------- | -------------
Content from cell 1         | Content from cell 2
Content in the first column | Content in the second column

First Header	Second Header
Content from cell 1	Content from cell 2
Content in the first column	Content in the second column

It's not really needed to align columns, this renders the exact same output:

First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second column

First Header	Second Header
Content from cell 1	Content from cell 2
Content in the first column	Content in the second column

For more complex cases, for instance having the leftmost upper cell blank, use this slightly more complex syntax:

|     | Second Header |
| --- | ------------- |
| Content from cell 1 | Content from cell 2 |
| Content in the first column | Content in the second column |

	Second Header
Content from cell 1	Content from cell 2
Content in the first column	Content in the second column

GitHub markdown specification (which DocFX extends) mandates at least three hyphens (---) in each column of the header row (like shown above on the first column).

The header row is always rendered in bold. If you also need the first column in bold, do this:

|              | Ease of use   | Awesomeness  |
| ------------ | ------------- | ------------ |
| **Web PKI**  | Very easy     | So good      |
| **Rest PKI** | Super easy    | Much awesome |
| **PKI SDK**  | Easy peasy    | Wow          | 

	Ease of use	Awesomeness
Web PKI	Very easy	So good
Rest PKI	Super easy	Much awesome
PKI SDK	Easy peasy	Wow

Text in cells is normally left-aligned. For other alignments:

| Left-aligned | Center-aligned | Right-aligned |
| :---         |     :---:      |          ---: |
| git status   | git status     | git status    |
| git diff     | git diff       | git diff      |

Left-aligned	Center-aligned	Right-aligned
git status	git status	git status
git diff	git diff	git diff

See also:

• Organizing information with tables - GitHub Help
• Examples
  • Table with leftmost upper cell blank: Web PKI / Introduction
  • Table with centered text: Web PKI / Browser support