Markdown/CommonMarklintingandstylecheckingforVisualStudioCode
IntroTheMarkdownmarkuplanguageisdesignedtobeeasytoread,write,andunderstand.Itsucceeds-anditsflexibilityisbothabenefitandadrawback.Manystylesarepossible,soformattingcanbeinconsistent.Someconstructsdon'tworkwellinallparsersandshouldbeavoided.Forexample,herearesomecommon/troublesomeMarkdownconstructs.
markdownlintisaVisualStudioCodeextensionthatincludesalibraryofrulestoencouragestandardsandconsistencyforMarkdownfiles.ItispoweredbymarkdownlintforNode.jswhichisbasedonmarkdownlintforRuby.
InstallOpenVisualStudioCodePressCtrl+P/⌘PtoopentheQuickOpendialogTypeextinstallmarkdownlinttofindtheextensionClicktheInstallbutton,thentheEnablebuttonOR
PressCtrl+Shift+X/⇧⌘XtoopentheExtensionstabTypemarkdownlinttofindtheextensionClicktheInstallbutton,thentheEnablebuttonOR
Openacommand-linepromptRuncode--install-extensionDavidAnson.vscode-markdownlintUseWheneditingaMarkdownfileinCodewithmarkdownlintinstalled,anylinesthatviolateoneofmarkdownlint'srules(seebelow)willtriggeraWarningintheeditor.WarningsareindicatedbyawavygreenunderlineandcanalsobeseenbypressingCtrl+Shift+M/⇧⌘MtoopentheErrorsandWarningsdialog.HoverthemousepointeroveragreenlinetoseethewarningorpressF8andShift+F8/⇧F8tocyclethroughallthewarnings(markdownlintwarningsallbeginwithMD###).Formoreinformationaboutamarkdownlintwarning,placethecursoronalineandclickthelightbulbiconorpressCtrl+./⌘.toopenthequickfixdialog.Clickingoneofthewarningsinthedialogwilldisplaythatrule'shelpentryinthedefaultwebbrowser.
Foratutorial,pleaseseeBuildanAmazingMarkdownEditorUsingVisualStudioCodeandPandocbyDaveJohnson.
RulesMD001heading-increment/header-increment-HeadinglevelsshouldonlyincrementbyonelevelatatimeMD002first-heading-h1/first-header-h1-FirstheadingshouldbeatoplevelheadingMD003heading-style/header-style-HeadingstyleMD004ul-style-UnorderedliststyleMD005list-indent-InconsistentindentationforlistitemsatthesamelevelMD006ul-start-left-ConsiderstartingbulletedlistsatthebeginningofthelineMD007ul-indent-UnorderedlistindentationMD009no-trailing-spaces-TrailingspacesMD010no-hard-tabs-HardtabsMD011no-reversed-links-ReversedlinksyntaxMD012no-multiple-blanks-MultipleconsecutiveblanklinesMD013line-length-LinelengthMD014commands-show-output-DollarsignsusedbeforecommandswithoutshowingoutputMD018no-missing-space-atx-NospaceafterhashonatxstyleheadingMD019no-multiple-space-atx-MultiplespacesafterhashonatxstyleheadingMD020no-missing-space-closed-atx-NospaceinsidehashesonclosedatxstyleheadingMD021no-multiple-space-closed-atx-MultiplespacesinsidehashesonclosedatxstyleheadingMD022blanks-around-headings/blanks-around-headers-HeadingsshouldbesurroundedbyblanklinesMD023heading-start-left/header-start-left-HeadingsmuststartatthebeginningofthelineMD024no-duplicate-heading/no-duplicate-header-MultipleheadingswiththesamecontentMD025single-title/single-h1-MultipletoplevelheadingsinthesamedocumentMD026no-trailing-punctuation-TrailingpunctuationinheadingMD027no-multiple-space-blockquote-MultiplespacesafterblockquotesymbolMD028no-blanks-blockquote-BlanklineinsideblockquoteMD029ol-prefix-OrderedlistitemprefixMD030list-marker-space-SpacesafterlistmarkersMD031blanks-around-fences-FencedcodeblocksshouldbesurroundedbyblanklinesMD032blanks-around-lists-ListsshouldbesurroundedbyblanklinesMD033no-inline-html-InlineHTMLMD034no-bare-urls-BareURLusedMD035hr-style-HorizontalrulestyleMD036no-emphasis-as-heading/no-emphasis-as-header-EmphasisusedinsteadofaheadingMD037no-space-in-emphasis-SpacesinsideemphasismarkersMD038no-space-in-code-SpacesinsidecodespanelementsMD039no-space-in-links-SpacesinsidelinktextMD040fenced-code-language-FencedcodeblocksshouldhavealanguagespecifiedMD041first-line-heading/first-line-h1-FirstlineinfileshouldbeatoplevelheadingMD042no-empty-links-NoemptylinksMD043required-headings/required-headers-RequiredheadingstructureMD044proper-names-PropernamesshouldhavethecorrectcapitalizationMD045no-alt-text-Imagesshouldhavealternatetext(alttext)MD046code-block-style-CodeblockstyleMD047single-trailing-newline-FilesshouldendwithasinglenewlinecharacterMD048code-fence-style-CodefencestyleSeemarkdownlint'sRules.mdfileformoredetails.
Thefollowingrulescanbeautomaticallyfixedbymovingthecursortoaruleviolation(wavyunderlinedtext)andtypingCtrl+./⌘.orclickingthelightbulbicon.
MD004ul-styleMD005list-indentMD006ul-start-leftMD007ul-indentMD009no-trailing-spacesMD010no-hard-tabsMD011no-reversed-linksMD012no-multiple-blanksMD014commands-show-outputMD018no-missing-space-atxMD019no-multiple-space-atxMD020no-missing-space-closed-atxMD021no-multiple-space-closed-atxMD022blanks-around-headingsMD023heading-start-leftMD026no-trailing-punctuationMD027no-multiple-space-blockquoteMD030list-marker-spaceMD031blanks-around-fencesMD032blanks-around-listsMD034no-bare-urlsMD037no-space-in-emphasisMD038no-space-in-codeMD039no-space-in-linksMD044proper-namesMD047single-trailing-newlineAllviolationsoftheaboverulesinthecurrentdocumentcanbefixedatoncebyrunningthemarkdownlint.fixAllcommand,eitherfromtheCommandPalette(viaView|CommandPalette...orCtrl+Shift+P/⇧⌘Pthensearchfor"markdownlint")orbybindingthecommandtoakeyboardshortcut.
ToautomaticallyfixtheseviolationswhensavingaMarkdowndocument,configureVisualStudioCode'seditor.codeActionsOnSavesettinglikeso:
"editor.codeActionsOnSave":{"source.fixAll.markdownlint":true}Automatically-appliedfixescanberevertedbyEdit|UndoorCtrl+Z/⌘Z.
TotemporarilydisablelintingofMarkdowndocuments,runthemarkdownlint.toggleLintingcommand(fromtheCommandPaletteorbybindingittoakeyboardshortcut).Tore-enablelinting,runthemarkdownlint.toggleLintingcommandagain.
Note:Theeffectsofthemarkdownlint.toggleLintingcommandareresetwhenanewworkspaceisopened;lintingdefaultstoenabled.
Configuremarkdownlint.configThedefaultruleconfigurationdisablesMD013/line-lengthbecausemanyfilesincludelineslongerthantheconventional80characterlimit:
{"MD013":false}Note:MD002/first-heading-h1andMD006/ul-start-leftarealsodisabledbecausetheyhavebeendeprecatedinthemarkdownlintlibrary.
Rulescanbeenabled,disabled,andcustomizedbycreatingaJSONfilenamed.markdownlint.jsonc/.markdownlint.jsonoraYAMLfilenamed.markdownlint.yaml/.markdownlint.ymloraJavaScriptfilenamed.markdownlint.jsinanydirectoryofaproject.Additionally,options(whichincluderulesandthingslikemarkdown-itpluginsandothersettings)canbeconfiguredbycreatingaJSONfilenamed.markdownlint-cli2.jsoncoraYAMLfilenamed.markdownlint-cli2.yamloraJavaScriptfilenamed.markdownlint-cli2.jsinanydirectoryofaproject.Formoreinformationaboutconfigurationfileprecedenceandcompleteexamples,seetheConfigurationsectionofthemarkdownlint-cli2README.md.
Note:Whennofolderisopen,configurationandoptionsareloadedfromtheuser'shomedirectory(e.g.,%USERPROFILE%onWindowsor$HOMEonmacOS/Linux).
Acustomconfigurationisoftendefinedbya.markdownlint.jsonfileintherootoftheproject:
{"default":true,"MD003":{"style":"atx_closed"},"MD007":{"indent":4},"no-hard-tabs":false}Toextendanotherconfigurationfile,suchafilecanusetheextendspropertytoprovidearelativepath:
{"extends":"../.markdownlint.json","no-hard-tabs":true}Filesreferencedviaextendsdonotneedtobepartofthecurrentproject(butusuallyare).
RulescanalsobeconfiguredusingCode'ssupportforuserandworkspacesettings.
TheaboveconfigurationmightlooklikethefollowinginCode'susersettingsfile:
{"editor.someSetting":true,"markdownlint.config":{"default":true,"MD003":{"style":"atx_closed"},"MD007":{"indent":4},"no-hard-tabs":false}}Filepathsreferencedbyextendsfromusersettingsareresolvedrelativetotheuser'shomedirectory(e.g.,%USERPROFILE%onWindowsor$HOMEonmacOS/Linux).Filepathsreferencedbyextendsfromworkspacesettingsareresolvedrelativetotheworkspacefolder.Filepathsreferencedbyextendsfromwithintheworkspaceareresolvedrelativetothefileitself.
Configurationsourceshavethefollowingprecedence(indecreasingorder):
.markdownlint-cli2.{jsonc,yaml,js}fileinthesameorparentdirectory.markdownlint.{jsonc,json,yaml,yml,js}fileinthesameorparentdirectoryVisualStudioCodeuser/workspacesettingsDefaultconfiguration(seeabove)Configurationchangessavedtoanylocationtakeeffectimmediately.Filesreferencedviaextendsarenotmonitoredforchanges.Inheritedconfigurationcanbeexplicitlydisabled(orre-enabled)inanyconfigurationfile.
Whenaworkspaceisopen,runningthemarkdownlint.openConfigFilecommand(fromtheCommandPaletteorbybindingittoakeyboardshortcut)willopenaneditorforthe.markdownlint.{jsonc,json,yaml,yml,js}configurationfileintherootoftheworkspace.Ifnoneofthesefilesexist,anew.markdownlint.jsoncontainingthedefaultruleconfigurationwillbeopenedintheeditorinthe"pendingsave"state.
markdownlint.focusModeBydefault,alllintingissuesareloggedandhighlightedasyoutypeoreditadocument.Thisincludes"transient"issueslikeMD009/no-trailing-spacessuchaswhentypingattheendofaline.
Ifyoufindthisdistracting,lintingcanbeconfiguredtoignoreissuesonthesamelineasthecursor.ThislookslikethefollowinginCode'susersettings:
{"editor.someSetting":true,"markdownlint.focusMode":true}markdownlint.runBydefault,lintingisperformedasyoutypeoreditadocument.Lintingisfastandefficientandshouldnotinterferewithtypicalworkflows.
Ifyoufindthisdistracting,lintingcanbeconfiguredtorunonlywhenthedocumentissaved.ThislookslikethefollowinginCode'susersettings:
{"editor.someSetting":true,"markdownlint.run":"onSave"}Note:WhenconfiguredtorunonSave,thelistofreportedissueswillbecomeoutdatedwhilethedocumentiseditedandwillupdatewhenthedocumentissaved.
markdownlint.ignoreIfaworkspacecontainsgeneratedcontentorotherMarkdownfilesthattriggerwarningsbutcannotbefixed,itmaybehelpfultoignore(skip)thosefileswhenlinting.Thiscanbedonebycreatingafilenamed.markdownlintignoreintherootoftheprojectorbyupdatingtheuser/workspaceconfiguration'smarkdownlint.ignoresettingwithanarrayofglobexpressionsmatchingtherelevantfilenames.Alternatively,themarkdownlint.ignoresettingcanbeastringidentifyingafiletouseinsteadof.markdownlintignore.
Whenusinga.markdownlintignorefile(oroverridingit),thecontentofthefilefollowstherulesforgitignoreandmaylooksomethinglike:
#IgnoreMarkdownfilesinthetestdirectorytest/*.md!test/except/this/one.mdAnexampleofusingCode'sworkspaceconfigurationtoignorefilesbyglobmightbe:
{"editor.someSetting":true,"markdownlint.ignore":["ignore.md","directory/ignore.md","**/ignore.md","**/*.md"]}Ortoignorefilesbyreferencingadifferentfile:
{"editor.someSetting":true,"markdownlint.ignore":".gitignore"}Theglobbinglibraryusedformatchingmarkdownlint.ignorearrayvaluesisminimatchwiththedotandnocommentoptionsenabled.Matchingiscase-sensitiveandpathsareresolvedrelativetotherootoftheworkspace.Thedirectoryseparatoris/,evenonWindows.
Note:Filescanalsobeignored(inawayothertoolswillrecognize)viatheignorespropertyin.markdownlint-cli2.{jsonc,yaml,js}.
markdownlint.customRulesCustomrulescanbespecifiedinCode'suser/workspaceconfigurationtoapplyadditionallintingbeyondthedefaultsetofrules.CustomrulesarespecifiedbythepathtoaJavaScriptfileorthenameoforpathtoannpmpackageexportingoneruleoranarrayofrules(examplesofcustomrules).
Pathsaretypicallyrelativetotherootofthecurrentworkspace(ortheuser'shomedirectorywhennofolderisopen)andshouldbeginwith./todifferentiatetherelativepathfromamoduleidentifier.Pathscanbeabsoluteandbeginwith/,thoughthisisdiscouragedbecauseitdoesnotworkreliablyacrossdifferentmachines.Ifimplementingcustomrulesinaworkspace,considercommittingtherulecodeunderthe.vscodedirectorywhereitwillbeseparatefromotherworkspacecontentandavailabletoeveryonewhoclonestherepository.Pathsoftheform{extension}/patharerelativetothebasedirectoryoftheCodeextensionnamedextension(whichmustalreadybeinstalled).Thissyntaxallowscustomrulestobeincludedwithinanotherextension'spackage,thoughthisisdiscouragedbecauseitintroducesasubtledependencyontheotherextension.
AnexampleofCode'sworkspacesettingsforcustomrulesmightlooklikethefollowing:
{"editor.someSetting":true,"markdownlint.customRules":["./.vscode/my-custom-rule.js","./.vscode/my-custom-rule-array.js","./.vscode/npm-package-for-custom-rule","/absolute/path/to/custom/rule.js","{publisher.extension-name}/custom-rule.js","{publisher.extension-name}/npm/rule/package"]}Forinformationaboutauthoringcustomrules,seethemarkdownlintdocumentationforcustomrules.
Note:Customrulescanalsobespecified(inawayothertoolswillrecognize)viathecustomRulespropertyin.markdownlint-cli2.{jsonc,yaml,js}.
SuppressIndividualwarningscanbesuppressedwithcommentsintheMarkdownfileitself:
评论