.markdownlintrc

{ // Summary: markdownlint config file for Cirq                    -*- jsonc -*-
  //
  // Note: there are multiple programs programs named "markdownlint". For
  // Cirq, we use https://github.com/igorshubovych/markdownlint-cli/, which is
  // the one you get with "brew install markdownlint" on MacOS.
  //
  // These settings try to stay close to the Google Markdown Style as
  // described at https://google.github.io/styleguide/docguide/style.html
  //
  // For a list of configuration options, see the following page:
  // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
  // (Beware that the above looks similar but is NOT the same as the page
  // https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md.)
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",

  // Require ATX-style headings.
  // https://google.github.io/styleguide/docguide/style.html#atx-style-headings
  "headings": {
    "style": "atx"
  },

  // Google style does not require that the first line of a file is a heading
  // for the title; it only states that the first heading should be a level 1.
  // https://google.github.io/styleguide/docguide/style.html#document-layout
  "first-line-heading": false,

  // The Google style does not define what to do about trailing punctuation in
  // headings. The markdownlint default disallows exclamation points, which
  // seems likely to be more annoying than useful – I have definitely seen
  // people use exclamation points in headings in README files on GitHub.
  // This setting removes exclamation point from the banned characters.
  "no-trailing-punctuation": {
    "punctuation": ".,;:。，；："
  },

  // No trailing spaces.
  // https://google.github.io/styleguide/docguide/style.html#trailing-whitespace
  "whitespace": {
    "br_spaces": 0
  },

  // Google style exempts some constructs from the line-length limit of 80 chars.
  // https://google.github.io/styleguide/docguide/style.html#exceptions
  "line-length": {
    "code_blocks": false,
    "headings": false,
    "tables": false
  },

  // Google Markdown style specifies 2 spaces after item numbers, 3 spaces
  // after bullets, so that the text itself is consistently indented 4 spaces.
  // https://google.github.io/styleguide/docguide/style.html#nested-list-spacing
  "list-marker-space": {
    "ol_multi": 2,
    "ol_single": 2,
    "ul_multi": 3,
    "ul_single": 3
  },

  "ul-indent": {
    "indent": 4
  },

  // Bare URLs are allowed in GitHub-flavored Markdown and in Google’s style.
  "no-bare-urls": false,

  // Basic Markdown allows raw HTML. Both GitHub & PyPI support subsets of
  // HTML, though it's unclear what subset PyPI supports. Google's style
  // guide doesn't disallow using HTML, although it recommends against it. (C.f.
  // the bottom of https://google.github.io/styleguide/docguide/style.html)
  // It's worth noting, though, that Google's guidance has Google's internal
  // documentation system in mind, and that system extends Markdown with
  // constructs that make it possible to accomplish things you can't do in
  // Markdown. Those extensions are also not available outside Google's system.
  // Thus, although a goal of this markdownlint configuration is to match
  // Google's style guide as closely as possible, these various factors suggest
  // it's reasonable to relax the HTML limitation. The list below is based on
  // https://github.com/github/markup/issues/245#issuecomment-682231577 plus
  // some things found elsewhere after that was written.
  "html": {
    "allowed_elements": [
      "a",
      "abbr",
      "b",
      "bdo",
      "blockquote",
      "br",
      "caption",
      "cite",
      "code",
      "dd",
      "del",
      "details",
      "dfn",
      "div",
      "dl",
      "dt",
      "em",
      "figcaption",
      "figure",
      "h1",
      "h2",
      "h3",
      "h4",
      "h5",
      "h6",
      "h7",
      "h8",
      "hr",
      "i",
      "img",
      "ins",
      "kbd",
      "li",
      "mark",
      "ol",
      "p",
      "picture",
      "pre",
      "q",
      "rp",
      "rt",
      "ruby",
      "s",
      "samp",
      "small",
      "source",
      "span",
      "span",
      "strike",
      "strong",
      "sub",
      "summary",
      "sup",
      "table",
      "tbody",
      "td",
      "tfoot",
      "th",
      "thead",
      "time",
      "tr",
      "tt",
      "ul",
      "var",
      "video",
      "wbr"
    ]
  }
}