{"id":3040,"date":"2026-08-11T11:30:49","date_gmt":"2026-08-11T15:30:49","guid":{"rendered":"https:\/\/csimmons.dev\/blog\/?p=3040"},"modified":"2026-08-11T11:30:49","modified_gmt":"2026-08-11T15:30:49","slug":"global-markdownlint-configuration-for-gfm-in-vs-code","status":"publish","type":"post","link":"https:\/\/csimmons.dev\/blog\/2026\/08\/global-markdownlint-configuration-for-gfm-in-vs-code\/","title":{"rendered":"Global Markdownlint Configuration for GFM in VS Code"},"content":{"rendered":"<p>I&#8217;ve been working on a lot of documentation lately, and I&#8217;ve been trying to adhere to standards by linting my Markdown in VS Code the same way I lint my code. That being said, I&#8217;ve grown weary of fighting the linter over a few rules.<\/p>\n<p><strong>Note:<\/strong> These instructions assume you are using macOS.<\/p>\n<p>Configure VS Code markdownlint with rules intended for <strong>GitHub Flavored Markdown (GFM)<\/strong>. These settings provide sensible defaults for writing README files and other Markdown documentation hosted on GitHub.<\/p>\n<h2>Create the Configuration File<\/h2>\n<p>Create a global <code>.markdownlint.json<\/code> file in your home directory:<\/p>\n<pre class=\"wp-block-code\"><code>touch ~\/.markdownlint.json<\/code><\/pre>\n<p>Add the following to <code>~\/.markdownlint.json<\/code>:<\/p>\n<pre class=\"wp-block-code\"><code class=\"language-json\">{\n    \"MD007\": {\n        \"indent\": 4\n    },\n    \"MD013\": false,\n    \"MD024\": {\n        \"siblings_only\": true\n    },\n    \"MD033\": false\n}<\/code><\/pre>\n<h2>Rules<\/h2>\n<ul>\n<li><strong>MD007 \u2014 Unordered list indentation<\/strong>\n<ul>\n<li>Uses <strong>4 spaces<\/strong> for nested unordered lists.<\/li>\n<li>This provides consistent indentation and works well with GitHub Flavored Markdown.<\/li>\n<\/ul>\n<\/li>\n<li><strong>MD013 \u2014 Line length<\/strong>\n<ul>\n<li>Disabled.<\/li>\n<li>Markdownlint normally limits lines to 80 characters.<\/li>\n<li>GFM does not require an 80-character line limit, so disabling this allows paragraphs and other content to remain on a single source line.<\/li>\n<\/ul>\n<\/li>\n<li><strong>MD024 \u2014 Duplicate headings<\/strong>\n<ul>\n<li>Configured with <code>siblings_only: true<\/code>.<\/li>\n<li>Allows the same heading name to appear in different sections.<\/li>\n<li>Duplicate headings under the same parent are still flagged.<\/li>\n<\/ul>\n<\/li>\n<li><strong>MD033 \u2014 Inline HTML<\/strong>\n<ul>\n<li>Disabled.<\/li>\n<li>Allows HTML inside Markdown documents.<\/li>\n<li>GitHub supports useful HTML elements such as <code>&lt;details&gt;<\/code>, <code>&lt;summary&gt;<\/code>, <code>&lt;kbd&gt;<\/code>, and <code>&lt;br&gt;<\/code>.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h2>Configure VS Code<\/h2>\n<p>Add the following to your VS Code <code>settings.json<\/code>:<\/p>\n<pre class=\"wp-block-code\"><code>\"markdownlint.configFile\": \"\/Users\/yourusername\/.markdownlint.json\",<\/code><\/pre>\n<p>Replace <code>yourusername<\/code> with your macOS username.<\/p>\n<p>Markdownlint will now use the global configuration for your Markdown files.<\/p>\n<h2>Project-Specific Configuration<\/h2>\n<p>If you only want the rules to apply to a specific project, create <code>.markdownlint.json<\/code> in the root of the project instead:<\/p>\n<pre class=\"wp-block-code\"><code class=\"language-text\">my-project\/\n\u251c\u2500\u2500 .markdownlint.json\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 ...<\/code><\/pre>\n<p>A project-level <code>.markdownlint.json<\/code> can be committed to Git with the rest of the project. This is especially useful for team projects because everyone who clones the repository can use the same Markdownlint rules.<\/p>\n<p>It also allows individual projects to define their own Markdown standards instead of relying on each developer&#8217;s global VS Code configuration.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;ve been working on a lot of documentation lately, and I&#8217;ve been trying to adhere to standards by linting my Markdown in VS Code the same way I lint my code. That being said, I&#8217;ve grown weary of fighting the linter over a few rules. Note: These instructions assume you are using macOS. Configure VS &#8230; <a title=\"Global Markdownlint Configuration for GFM in VS Code\" class=\"read-more\" href=\"https:\/\/csimmons.dev\/blog\/2026\/08\/global-markdownlint-configuration-for-gfm-in-vs-code\/\" aria-label=\"Read more about Global Markdownlint Configuration for GFM in VS Code\">Read more<\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_exactmetrics_skip_tracking":false,"_cloudinary_featured_overwrite":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[68],"tags":[80,79,53],"class_list":["post-3040","post","type-post","status-publish","format-standard","hentry","category-developer","tag-github","tag-markdown","tag-vscode"],"jetpack_shortlink":"https:\/\/wp.me\/pbVg43-N2","jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts\/3040","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/comments?post=3040"}],"version-history":[{"count":1,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts\/3040\/revisions"}],"predecessor-version":[{"id":3044,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts\/3040\/revisions\/3044"}],"wp:attachment":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/media?parent=3040"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/categories?post=3040"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/tags?post=3040"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}