<commit_before># Validate your markdown files

In GFM, we can write any document with right syntax. For example, we can write html tag `<h1>title</h1>` instead of markdown syntax `#title`. But for some purpose, some behaviors are unwanted, so we add markdown validators for each markdown document.

In this document, you'll learn how to define markdown validation rules, which will help you to validate markdown documents in an efficient way.

*This is part of DFM, if you switch markdown engine to other engine, validation might not work.*

## How to config markdown validation rules

Create a *JSON* file with name `md.style` in the same folder of `docfx.json`, and with following content:
```json
{
   "rules": [],
   "tagRules": []
}
```

## Build-in html tag validation rules

For most cases, you may want to prohibit using certain html tags in markdown, so we built a built-in html tag rule for you.

For example, create `md.style` with following content:
```json
{
   "tagRules": [
      {
         "tagName": [ "H1", "H2" ],
         "behavior": "Warning",
         "messageFormatter": "Some message.",
         "customValidatorContractName": null,
         "openingTagOnly": false
      }
   ]
}
```
Then when any one write `<H1>` or `<H2>` in markdown file, it will give a warning with message `Some message.`.

1.  `tagName` is filter html tag names, *required*, *case-insensitive*.
2.  `behavior` is an enum value, *required*.

    it can be following:
    * None: Do nothing.
    * Warning: Log a warning.
    * Error: Log an error, it will break current build.
3.  `messageFormatter` is the log message when hit, *required*.
    It can contain following variables:
    * `{0}` the name of tag.
    * `{1}` the whole tag.
    For example, the `messageFormatter` is `{0} is the tag name of {1}.`, and the tag is `<H1 class="heading">` match the rule, then it will output following message: `H1 is the tag name of <H1 class="heading">.`
4.  `customValidatorContractName` is an extension tag rule contract name for complex validation rule, *option*.

    see [How to create a custom html tag validator](#how-to-create-a-custom-html-tag-validator).
5.  `openingTagOnly` is a boolean, *option*, default is `false`

    if `true`, it will only apply to opening tag, e.g. `<H1>`, otherwise, it will also apply to closing tag, e.g. `</H1>`.

### How to create a custom html tag validator
1.  Create a project in your code editor (e.g. visual studio).
2.  Add nuget package `Microsoft.DocAsCode.Plugins` and `Microsoft.Composition`.
3.  Create a class and implements @Microsoft.DocAsCode.Plugins.ICustomMarkdownTagValidator.
4.  Add ExportAttribute with contract name.

For example, we require tags should contain text `class`:
```csharp
[Export("Require text class", typeof(ICustomMarkdownTagValidator))]
public class MyMarkdownTagValidator : ICustomMarkdownTagValidator
{
    public bool Validate(string tag)
    {
        return tag.Contains("class");
    }
}
```
And update your `md.style` with following content:
```json
{
   "tagRules": [
      {
         "tagName": [ "H1", "H2" ],
         "behavior": "Warning",
         "messageFormatter": "Some message.",
         "customValidatorContractName": "Require text class",
         "openingTagOnly": true<commit_msg>fix error in document.<commit_after># Validate your markdown files

In GFM, we can write any document with right syntax. For example, we can write html tag `<h1>title</h1>` instead of markdown syntax `#title`. But for some purpose, some behaviors are unwanted, so we add markdown validators for each markdown document.

In this document, you'll learn how to define markdown validation rules, which will help you to validate markdown documents in an efficient way.

*This is part of DFM, if you switch markdown engine to other engine, validation might not work.*

## How to config markdown validation rules

Create a *JSON* file with name `md.style` in the same folder of `docfx.json`, and with following content:
```json
{
   "rules": [],
   "tagRules": []
}
```

## Build-in html tag validation rules

For most cases, you may want to prohibit using certain html tags in markdown, so we built a built-in html tag rule for you.

For example, create `md.style` with following content:
```json
{
   "tagRules": [
      {
         "tagNames": [ "H1", "H2" ],
         "behavior": "Warning",
         "messageFormatter": "Some message.",
         "customValidatorContractName": null,
         "openingTagOnly": false
      }
   ]
}
```
Then when any one write `<H1>` or `<H2>` in markdown file, it will give a warning with message `Some message.`.

1.  `tagNames` is filter html tag names, *required*, *case-insensitive*.
2.  `behavior` is an enum value, *required*.

    it can be following:
    * None: Do nothing.
    * Warning: Log a warning.
    * Error: Log an error, it will break current build.
3.  `messageFormatter` is the log message when hit, *required*.
    It can contain following variables:
    * `{0}` the name of tag.
    * `{1}` the whole tag.
    For example, the `messageFormatter` is `{0} is the tag name of {1}.`, and the tag is `<H1 class="heading">` match the rule, then it will output following message: `H1 is the tag name of <H1 class="heading">.`
4.  `customValidatorContractName` is an extension tag rule contract name for complex validation rule, *option*.

    see [How to create a custom html tag validator](#how-to-create-a-custom-html-tag-validator).
5.  `openingTagOnly` is a boolean, *option*, default is `false`

    if `true`, it will only apply to opening tag, e.g. `<H1>`, otherwise, it will also apply to closing tag, e.g. `</H1>`.

### How to create a custom html tag validator
1.  Create a project in your code editor (e.g. visual studio).
2.  Add nuget package `Microsoft.DocAsCode.Plugins` and `Microsoft.Composition`.
3.  Create a class and implements @Microsoft.DocAsCode.Plugins.ICustomMarkdownTagValidator.
4.  Add ExportAttribute with contract name.

For example, we require tags should contain text `class`:
```csharp
[Export("Require text class", typeof(ICustomMarkdownTagValidator))]
public class MyMarkdownTagValidator : ICustomMarkdownTagValidator
{
    public bool Validate(string tag)
    {
        return tag.Contains("class");
    }
}
```
And update your `md.style` with following content:
```json
{
   "tagRules": [
      {
         "tagNames": [ "H1", "H2" ],
         "behavior": "Warning",
         "messageFormatter": "Some message.",
         "customValidatorContractName": "Require text class",
         "openingTagOnly": true
{'fraction_non_alphanumeric': 0.11075563680682511, 'fraction_numerical': 0.007921998781230956, 'mean_word_length': 3.5621959694232106, 'pattern_counts': {'":': 28, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3103907', 'n_tokens_mistral': 1928, 'n_tokens_neox': 1883, 'n_words': 830}