remarkrc.yml

---

# This is the top level remark configuration file. You may need to make a local
# copy to override settings at a project level.

# To install all the required plugins:
#
#   npm i -g $(grep remark-lint ~/.remarkrc.yml | \
#       sed -e '/\s*#/d' -e 's/^  - \(- \)\?//')

# These 'settings' affect the `remark-stringify` formater, not the linter, and
# are mostly covered in https://github.com/syntax-tree/mdast-util-to-markdown
settings:

  # Markers (all set to defaults)
  bullet: '*'
  bulletOrdered: '.'
  fence: '`'
  strong: '*'
  emphasis: '*'

  # Use a different marker for contrast
  rule: '-'

  # Always use fences for code blocks to match Markdown Style Guide (MSG)
  fences: true

  # Indent the content of list items with the size of the bullet plus one space
  # For consistency with editor settings
  listItemIndent: one

  # Personal preference: draw a long line of dashes for a thematic break
  ruleRepetition: 80


plugins:

  # --- Message Control -------------------------------------------------------#
  # Enable, disable, or ignore linting messages via comments in your Markdown.
  # See https://github.com/remarkjs/remark-message-control

  - - remark-message-control
    - name: lint

  # --- Git Flavoured Markdown ------------------------------------------------#
  # Add support for parsing GFM tables, tasklists, strikethrough, and autolinks.
  # See https://github.com/remarkjs/remark-gfm
  # Must be loaded before presets and rules since additional parsing may be
  # required for those rules to be applied.  Note that the default option
  # settings for the plugin correspond to the default option settings for the
  # rules.

  - - remark-gfm

  # --- Processfrontmatter -------------------------------------#
  # Ignore intial frontmatter in 
  # See https://github.com/micromark/micromark-extension-frontmatter
  # - remark-frontmatter

  # --- Linting Presets -------------------------------------------------------#
  # Must be loaded before rule and setting overides

  # Consistent Preset (aka C)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent
  # - remark-preset-lint-consistent

  # Recommended Preset (aka R)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended
  - remark-preset-lint-recommended

  # Markdown Style Guide Preset (aka MSG)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide
  - remark-preset-lint-markdown-style-guide

  # --- Linting Rules and Settings --------------------------------------------#
  # See https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md
  
  # Many of the following are commented out because they are implied by the
  # preset rules. If a preset includes a rule we add its code to the list at
  # the end of its description.  For each rule setting, we also note whether
  # it is  the default or set via a preset with a similar comment.

  # # Warn when table cells are incorrectly padded (MSG, C)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding
  # - - remark-lint-table-cell-padding
  # # - consistent  # (default, C)
  # # - compact
  #   - padded      # (MSG)

  # # Warn when table rows are not fenced with pipes (MSG)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipes
  # - remark-lint-table-pipes

  # # Warn when table pipes are not aligned (MSG)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipe-alignment
  # - remark-lint-table-pipe-alignment

  # # Warn when tables are indented (MSG)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-table-indentation
  # - remark-lint-no-table-indentation

  # Warn when list item checkboxes are inconsistent (C)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-character-style
  - - remark-lint-checkbox-character-style
  # - consistent                         # (default, C)
    - {checked: 'x', unchecked: ' '}     # matches formatter default

  # Warn when list item checkboxes are followed by too much whitespace
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-content-indent
  - remark-lint-checkbox-content-indent

  # Warn when strikethrough markers violate the given style
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strikethrough-marker
  - - remark-lint-strikethrough-marker
  # - consistent    # (default)
  # - '~'           # github allows this
    - '~~'          # strict GFM spec ('~' might be used in a file path)
  # TODO: not working at the moment ... investigate

  # --- remark-lint ----------------------------------------------------------#

  # # Warn when a heading does not conform to the ATX style (MSG, C)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style
  # - - remark-lint-heading-style
  # # - consistent  # (default, C)
  # # - atx-closed  #       matches formatter setting `closeAtx: true`
  # # - setext      #       matches formatter setting `setext: true`
  #   - atx         # (MSG) matches formatter default

  # # Warn when importance (strong) markers violate the given style (MSG, C)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker
  # - - remark-lint-strong-marker
  # # - consistent # (C) default 
  # # - '_'        #       matches formatter setting `strong: _`
  #   - '*'        # (MSG) matches formatter default

  # # Warn if using emphasis markers other than configured (MSG, C)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-emphasis-marker
  # - - remark-lint-emphasis-marker
  # # - consistent # (C) default 
  # # - '_'        #       matches formatter setting `emphasis: _`
  #   - '*'        # (MSG) matches formatter default

  # # Warn if using fenced code markers other than configured (MSG, C)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker
  # - - remark-lint-fenced-code-marker
  # # - consistent # (C) default 
  # # - '~'     # matches formatter setting `fence: ~`
  #   - '`'     # (default, MSG) formatter default

  # # Warn when code blocks do not adhere to the `fenced` style (MSG, C)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style
  # - - remark-lint-code-block-style
  # # - consistent  # (C)
  # # - indented    #       matches formatter default if no flags
  #   - fenced      # (MSG) matches formatter setting `fences: true`

  # Warn when horizontal rules violate a given style (MSG, C)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style
  - - remark-lint-rule-style
  # - consistent  # (C)
  # - '***'       # (default) matches formatter default
  # - '---'       # (MSG)     matches formatter setting `rule: -`
    - '--------------------------------------------------------------------------------'
  # # ^ matches formatter settings `rule: '-'` and `ruleRepetition: 80`
  # # This is a personal preference

  # Warn when a bullet and content are not seperated by a single space. (MSG, R)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent
  - - remark-lint-list-item-indent
  # - tab-size   # (R)   matches formatter setting `listItemIndent: tab`
  # - mixed      # (MSG) matches formatter setting `listItemIndent: mixed`
    - space      #       matches formatter setting `listItemIndent: one`

  # Warn when the marker value of ordered lists violates a given style (MSG)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value
  - - remark-lint-ordered-list-marker-value
  # - one     # (MSG)     not enforcable by formatter     
  # - single  #           matches formatter setting `incrementListMarker: false`
    - ordered # (default) matches formatter default

  # # Warn when the markers of ordered lists violate the given style (MSG, C, R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style
  # - - remark-lint-ordered-list-marker-style
  # # - consistent # (default, C) 
  # # - ')'        #              matches formatter setting `bulletOrdered: )`
  #   - '.'        # (MSG, R)     matches formatter default

  # Warn when markers for unordered lists violate a given style
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-unordered-list-marker-style
  - - remark-lint-unordered-list-marker-style
  # - consistent # (default) 
  # - '-'        # (MSG)     matches formatter setting `bullet: -`
  # - '+'        # (MSG)     matches formatter setting `bullet: +`
    - '*'        #           matches formatter default

  #### The following mandatory rules match output enforced by the formater

  # # Warn when the content of a list item has mixed indentation (MSG, C)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent
  # - remark-lint-list-item-content-indent

  # # Warn for autolinks without protocol (MSG, R)
  # # Autolinks are URLs enclosed in < and > characters
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-auto-link-without-protocol
  # - remark-lint-no-auto-link-without-protocol

  # # Warn when blank lines without > markers are in a block quote (MSG, R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker
  # - remark-lint-no-blockquote-without-marker

  # # Warn when URLs without angle brackets are used (MSG, R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls
  # - remark-lint-no-literal-urls

  # # Warn for too many consecutive blank lines (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-consecutive-blank-lines
  # - remark-lint-no-consecutive-blank-lines

  # # Warn when heading content is indented (R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-content-indent
  # - remark-lint-no-heading-content-indent

  # # Warn when list item bullets are indented (R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-bullet-indent
  # - remark-lint-list-item-bullet-indent

  # # Warn when a newline at the end of a file is missing (R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-newline
  # - remark-lint-final-newline

  # Warn when missing blank lines before block content (maybe except for lists)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-missing-blank-lines
  - - remark-lint-no-missing-blank-lines
  # - exceptTightLists: false # (default)
    - exceptTightLists: true  #           matches formatter default

  # Warn when headings are indented
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-indent
  - remark-lint-no-heading-indent

  # Warn when linebreaks use an inconsistent style
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-linebreak-style
  - - remark-lint-linebreak-style
  # - unix # (default) matches formatter default
  
  # Warn when hard tabs are used instead of spaces
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-tabs
  # - remark-lint-no-tabs
  # XXX: vim settings avoid this issue

  # ---------------------------------------------------------------------
  # Warnings that are not fixed by the formatter

  # Warn when link and definition titles have inconsistent quotes (MSG, C)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style
  - - remark-lint-link-title-style
  # - consistent # (default, C)
  # - '\''       # 
  # - '()'       # 
  # - '"'        # (MSG)
    - false 
  # XXX: The formatter uses single or double quotes depending on the contents of
  # the title. There is no setting that will accommodates this, so we disable
  # this rule.
  
  # # Warn when blockquotes are indented inconsistently (MSG, C)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation
  # - - remark-lint-blockquote-indentation
  # # - consistent  # (C)
  #   - 1           # (MSG)
  
  # # Warn when more than 2 spaces are used to create a hard break (MSG, R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces
  # - remark-lint-hard-break-spaces

  # # Warn when shortcut reference images are used (MSG, R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-image
  # - remark-lint-no-shortcut-reference-image

  # # Warn when shortcut reference links are used (MSG, R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-link
  # - remark-lint-no-shortcut-reference-link

  # # Warn when headings are longer than 60 characters (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-heading-length
  # - - remark-lint-maximum-heading-length
  #   - 60 # (default, MSG)

  # Warn when lines are too long (except headings, tables, code, defns) (MSG)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-line-length
  - - remark-lint-maximum-line-length
  # - 80    # (default, MSG)
    - false
  # XXX: Some sites like GitLab really don't like the hard wrapping and want
  # paragraphs all on one line, so I turn this off and let VIM to do
  # soft-wrapping instead.

  # # Warn when definition labels are not lowercase (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-case
  # - remark-lint-definition-case

  # # Warn when consecutive whitespace is used in a definition label (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing
  # - remark-lint-definition-spacing

  # # Warn if fenced code blocks do not have a langauge flag (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag
  # - - remark-lint-fenced-code-flag
  # # - ['bash', 'js', 'markdown', ...]   
  #   - allowEmpty: false   # (MSG)

  # # Warn when definitions are placed other than at the end of the file (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition
  # - remark-lint-final-definition

  # # Warn when list looseness is incorrect (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing
  # - - remark-lint-list-item-spacing
  #   - checkBlanks: false  # (default, MSG)

  # # Warn on duplicate headings (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings
  # - remark-lint-no-duplicate-headings
  - - remark-lint-no-duplicate-headings
    - false

  # # Warn when emphasis, instead of a heading, introduces a paragraph  (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-emphasis-as-heading
  # - remark-lint-no-emphasis-as-heading

  # # Warn when headings end in (the specified) illegal characters (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-punctuation
  # - - remark-lint-no-heading-punctuation
  # # - '.,;:!?' # (default)
  #   - '.:'     # (MSG)

  # # Warn when multiple top level headings are used (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-multiple-toplevel-headings
  # - remark-lint-no-multiple-toplevel-headings

  # # Warn when shell code is prefixed by dollars (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars
  # - remark-lint-no-shell-dollars

  # # Warn when headings increment with more than 1 level at a time (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-increment
  # - remark-lint-heading-increment

  # Warn when the first heading has a level other than '1'.
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-first-heading-level
  - - remark-lint-first-heading-level
  # - 2  # example for, say, a markdown fragment to be included in another file
  # - 1  # (default)

  # Warn for empty URLs in links and images
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-empty-url
  # - remark-lint-no-empty-url
  # XXX: better in a post-commit hook

  # Warn when duplicate headings are found, but only when on the same level
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings-in-section
  - remark-lint-no-duplicate-headings-in-section

  # Warn when definitions define the same URL
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls
  - remark-lint-no-duplicate-defined-urls

  # Warn when HTML nodes are used (except for comments)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-html
  # - remark-lint-no-html
  # XXX: depends on publishing target

  # Warn when the content in paragraphs are indented
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-paragraph-content-indent
  - remark-lint-no-paragraph-content-indent

  # Warn when URLs are also defined identifiers
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-reference-like-url
  # (might get mixed up with auto-links)
  - remark-lint-no-reference-like-url

  # Warn when full reference images are used if they can be collapsed
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-image
  # - remark-lint-no-unneeded-full-reference-image
  # XXX: limited utility

  # Warn when full reference links are used if they can be collapsed
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link
  # - remark-lint-no-unneeded-full-reference-link
  # XXX: limited utility

  # Warn if too many hashes (h7+ “headings”)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-like-paragraph
  - remark-lint-no-heading-like-paragraph

  # --- MSG Rules that are more suitable for a pre-commit hooks ---------------#

  # # Warn when file name start with an article (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-articles
  - - remark-lint-no-file-name-articles
    - false

  # # Warn when file names contain consecutive dashes (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-consecutive-dashes
  - - remark-lint-no-file-name-consecutive-dashes
    - false

  # # Warn when file names contain irregular characters (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-irregular-characters
  - - remark-lint-no-file-name-irregular-characters
    - false

  # # Warn when file names use mixed case (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-mixed-case
  - - remark-lint-no-file-name-mixed-case
    - false

  # # Warn when file names contain initial or final dashes (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-outer-dashes
  - - remark-lint-no-file-name-outer-dashes
    - false

  # # Warn when the file extension is not '.md' (MSG)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-file-extension
  - - remark-lint-file-extension
  # - md  # (default, MSG)
    - false
      
  # --- Recomended Rules that are more suitable for a pre-commit hooks --------#

  # # Warn when inline nodes (emphasis,links,...) are padded with spaces (R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-inline-padding
  - - remark-lint-no-inline-padding
    - false

  # Warn when duplicate definitions are found (R)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions
  - - remark-lint-no-duplicate-definitions
    - false

  # Warn when references to undefined definitions are found (R)
  # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references
  - - remark-lint-no-undefined-references
  # - allow: ['...']   # example to allow, say, `[...]` for elided content
    - false
  
  # # Warn when unused definitions are found (R)
  # # See https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions
  - - remark-lint-no-unused-definitions
    - false