Add a .markdownlintrc config file for Markdown file linter#1011
Add a .markdownlintrc config file for Markdown file linter#1011mhucka wants to merge 1 commit intotensorflow:masterfrom
.markdownlintrc config file for Markdown file linter#1011Conversation
Add a config for `markdownlint` that tries to stay close to TensorFlow's documentation style and Google's Markdown Style Guide.
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a configuration file for Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a .markdownlintrc configuration file to enforce a consistent style for Markdown documents, aligning with TensorFlow and Google style guides. The configuration is well-structured and documented with comments. However, the use of comments in a .markdownlintrc file will cause parsing errors with markdownlint-cli, as it expects a standard JSON format. My review includes a suggestion to remove the comments to make the file valid.
| { // -*- jsonc -*- | ||
| // | ||
| // Copyright 2026 The TensorFlow Authors. All Rights Reserved. | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // https://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| // Summary: config "markdownlint" to approximate TensorFlow's style (which in | ||
| // turn is close to https://google.github.io/styleguide/docguide/style.html). | ||
| // Note: there are multiple programs named "markdownlint" ; we use | ||
| // https://github.com/igorshubovych/markdownlint-cli/. | ||
|
|
||
| "$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. | ||
| "line-length": { | ||
| "line_length": 80, | ||
| "code_block_line_length": 80, | ||
| "heading_line_length": 80, | ||
| "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 | ||
| // recommends against using raw HTML, but does allow it. (C.f. the bottom of | ||
| // https://google.github.io/styleguide/docguide/style.html) Google's in-house | ||
| // documentation system allows many inline and block-level tags, but strips | ||
| // others that can pose security risks (e.g., <object> and standalone <svg>). | ||
| // The list below tries to capture the intersection of what GitHub allows | ||
| // (c.f. https://github.com/github/markup/issues/245#issuecomment-682231577), | ||
| // what PyPI seems to allow, what Google allows, and what seems likely to be | ||
| // most useful in situations where someone needs to reach for HTML. | ||
| "html": { | ||
| "allowed_elements": [ | ||
| "a", | ||
| "abbr", | ||
| "b", | ||
| "blockquote", | ||
| "br", | ||
| "caption", | ||
| "cite", | ||
| "code", | ||
| "dd", | ||
| "del", | ||
| "details", | ||
| "dfn", | ||
| "div", | ||
| "dl", | ||
| "dt", | ||
| "em", | ||
| "figcaption", | ||
| "figure", | ||
| "h1", | ||
| "h2", | ||
| "h3", | ||
| "h4", | ||
| "h5", | ||
| "h6", | ||
| "hr", | ||
| "i", | ||
| "img", | ||
| "ins", | ||
| "kbd", | ||
| "li", | ||
| "mark", | ||
| "ol", | ||
| "p", | ||
| "picture", | ||
| "pre", | ||
| "q", | ||
| "s", | ||
| "samp", | ||
| "small", | ||
| "span", | ||
| "strong", | ||
| "sub", | ||
| "summary", | ||
| "sup", | ||
| "table", | ||
| "tbody", | ||
| "td", | ||
| "tfoot", | ||
| "th", | ||
| "thead", | ||
| "time", | ||
| "tr", | ||
| "tt", | ||
| "ul", | ||
| "var", | ||
| "wbr" | ||
| ] | ||
| } | ||
| } |
There was a problem hiding this comment.
This file is named .markdownlintrc, but it contains comments, which makes it invalid JSON. According to the markdownlint-cli documentation (which this PR aims to support), a .markdownlintrc file is parsed as standard JSON. The comments will cause a parsing failure when the linter tries to load this configuration.
To make this configuration file functional, it needs to be valid JSON. Please remove all comments.
{
"$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
"headings": {
"style": "atx"
},
"first-line-heading": false,
"no-trailing-punctuation": {
"punctuation": ".,;:。，；："
},
"whitespace": {
"br_spaces": 0
},
"line-length": {
"line_length": 80,
"code_block_line_length": 80,
"heading_line_length": 80,
"code_blocks": false,
"headings": false,
"tables": false
},
"list-marker-space": {
"ol_multi": 2,
"ol_single": 2,
"ul_multi": 3,
"ul_single": 3
},
"ul-indent": {
"indent": 4
},
"no-bare-urls": false,
"html": {
"allowed_elements": [
"a",
"abbr",
"b",
"blockquote",
"br",
"caption",
"cite",
"code",
"dd",
"del",
"details",
"dfn",
"div",
"dl",
"dt",
"em",
"figcaption",
"figure",
"h1",
"h2",
"h3",
"h4",
"h5",
"h6",
"hr",
"i",
"img",
"ins",
"kbd",
"li",
"mark",
"ol",
"p",
"picture",
"pre",
"q",
"s",
"samp",
"small",
"span",
"strong",
"sub",
"summary",
"sup",
"table",
"tbody",
"td",
"tfoot",
"th",
"thead",
"time",
"tr",
"tt",
"ul",
"var",
"wbr"
]
}
}
mhucka
added
area/docs
1 participant
In preparation for more work on documentation, and to help contributors get the formatting right, this adds a config file for the program
markdownlintthat tries to stay close to TensorFlow's documentation style and Google's Markdown Style Guide.Note: there is currently no script to run
markdownlintor checks in CI. Those can come later. This config file nevertheless helps people get the right settings in their editors and makes it possible to use a markdownlint pre-commit hook for git.