[{"data":1,"prerenderedAt":840},["ShallowReactive",2],{"guide-markdown-writing-workflow":3},{"id":4,"title":5,"body":6,"date":832,"description":833,"extension":834,"meta":835,"navigation":537,"path":836,"readingTime":547,"seo":837,"stem":838,"__hash__":839},"guides\u002Fguides\u002Fmarkdown-writing-workflow.md","Markdown Writing Workflow: Edit, Preview, and Export",{"type":7,"value":8,"toc":800},"minimark",[9,14,18,21,25,28,33,36,114,117,121,124,133,137,140,175,178,182,185,189,227,231,234,248,252,255,259,266,313,316,320,331,356,360,370,395,398,402,405,408,434,437,440,443,473,476,479,482,502,505,508,511,594,597,601,604,608,611,657,664,668,671,691,694,698,701,720,723,727,735,738,742,762,766,786,790,796],[10,11,13],"h2",{"id":12},"why-your-workflow-matters","Why Your Workflow Matters",[15,16,17],"p",{},"A good writing workflow removes friction between thinking and publishing. When you edit, preview, and export smoothly, you spend time on content — not on fighting tools, wrestling with formats, or untangling Git conflicts.",[15,19,20],{},"Markdown's plain-text nature makes it uniquely suited for structured, repeatable workflows. This guide walks you through building one that scales from personal notes to team documentation.",[10,22,24],{"id":23},"the-edit-preview-export-pipeline","The Edit-Preview-Export Pipeline",[15,26,27],{},"Every Markdown workflow has three stages.",[29,30,32],"h3",{"id":31},"edit","Edit",[15,34,35],{},"Write raw Markdown in a text editor. The right editor depends on your needs:",[37,38,39,55],"table",{},[40,41,42],"thead",{},[43,44,45,49,52],"tr",{},[46,47,48],"th",{},"Editor",[46,50,51],{},"Strength",[46,53,54],{},"Best For",[56,57,58,70,81,92,103],"tbody",{},[43,59,60,64,67],{},[61,62,63],"td",{},"VS Code",[61,65,66],{},"Extensions, Git integration",[61,68,69],{},"Technical docs",[43,71,72,75,78],{},[61,73,74],{},"Typora",[61,76,77],{},"Inline WYSIWYG",[61,79,80],{},"Long-form writing",[43,82,83,86,89],{},[61,84,85],{},"Obsidian",[61,87,88],{},"Linking, backlinks",[61,90,91],{},"Knowledge bases",[43,93,94,97,100],{},[61,95,96],{},"Neovim \u002F Helix",[61,98,99],{},"Speed, keyboard-driven",[61,101,102],{},"Terminal-native writers",[43,104,105,108,111],{},[61,106,107],{},"Browser tools",[61,109,110],{},"Zero setup, shareable",[61,112,113],{},"Quick edits, collaboration",[15,115,116],{},"Pick one editor and learn it well. Switching tools constantly fragments your muscle memory.",[29,118,120],{"id":119},"preview","Preview",[15,122,123],{},"Before you publish, verify your formatting. Real-time preview lets you catch errors as you write — broken tables, missing images, malformed links.",[15,125,126,127,132],{},"Use our ",[128,129,131],"a",{"href":130},"\u002Ftools\u002Fmarkdown-preview","Markdown Preview"," for instant browser-based rendering. For local workflows, VS Code's preview pane or Typora's inline mode work well.",[29,134,136],{"id":135},"export","Export",[15,138,139],{},"Convert your Markdown into the format your audience needs. Common targets:",[141,142,143,151,157,163,169],"ul",{},[144,145,146,150],"li",{},[147,148,149],"strong",{},"HTML"," — web pages, blogs, CMS content",[144,152,153,156],{},[147,154,155],{},"PDF"," — printable documentation, reports",[144,158,159,162],{},[147,160,161],{},"DOCX"," — collaboration with non-technical stakeholders",[144,164,165,168],{},[147,166,167],{},"Slides"," — presentations via Marp, Slidev, or reveal.js",[144,170,171,174],{},[147,172,173],{},"EPUB"," — e-books and long-form reading",[15,176,177],{},"Each export format has its own tooling. The key is to automate the step so you never export manually more than once.",[10,179,181],{"id":180},"version-control-and-markdown","Version Control and Markdown",[15,183,184],{},"Markdown's plain-text format makes it a natural fit for Git. You get line-level diffs, meaningful commit messages, and branch-based review workflows.",[29,186,188],{"id":187},"best-practices-for-git-markdown","Best Practices for Git + Markdown",[141,190,191,197,203,217],{},[144,192,193,196],{},[147,194,195],{},"Commit logically"," — one section or topic per commit, not one giant dump",[144,198,199,202],{},[147,200,201],{},"Write descriptive messages"," — \"Add API authentication section\" beats \"update docs\"",[144,204,205,212,213,216],{},[147,206,207,208],{},"Use ",[209,210,211],"code",{},".gitattributes"," — set ",[209,214,215],{},"*.md text eol=lf"," to normalize line endings across Windows and macOS",[144,218,219,226],{},[147,220,221,222,225],{},"Enable ",[209,223,224],{},"markdownlint"," in CI"," — catch formatting issues before merge",[29,228,230],{"id":229},"avoiding-merge-conflicts","Avoiding Merge Conflicts",[15,232,233],{},"Long paragraphs create painful conflicts. To reduce them:",[141,235,236,239,242,245],{},[144,237,238],{},"Keep paragraphs short — 3–4 lines maximum",[144,240,241],{},"Put each list item on its own line",[144,243,244],{},"Break long documents into smaller files and use transclusion or includes where your platform supports it",[144,246,247],{},"Use reference-style links to keep prose lines short",[10,249,251],{"id":250},"markdown-in-cicd-pipelines","Markdown in CI\u002FCD Pipelines",[15,253,254],{},"Automating Markdown checks in your CI pipeline prevents broken content from reaching production.",[29,256,258],{"id":257},"linting","Linting",[15,260,261,262,265],{},"Add ",[209,263,264],{},"markdownlint-cli"," to your pipeline:",[267,268,273],"pre",{"className":269,"code":270,"language":271,"meta":272,"style":272},"language-yaml shiki shiki-themes github-light github-dark","# GitHub Actions example\n- name: Lint Markdown\n  run: npx markdownlint-cli \"**\u002F*.md\" --ignore node_modules\n","yaml","",[209,274,275,284,302],{"__ignoreMap":272},[276,277,280],"span",{"class":278,"line":279},"line",1,[276,281,283],{"class":282},"sJ8bj","# GitHub Actions example\n",[276,285,287,291,295,298],{"class":278,"line":286},2,[276,288,290],{"class":289},"sVt8B","- ",[276,292,294],{"class":293},"s9eBZ","name",[276,296,297],{"class":289},": ",[276,299,301],{"class":300},"sZZnC","Lint Markdown\n",[276,303,305,308,310],{"class":278,"line":304},3,[276,306,307],{"class":293},"  run",[276,309,297],{"class":289},[276,311,312],{"class":300},"npx markdownlint-cli \"**\u002F*.md\" --ignore node_modules\n",[15,314,315],{},"This catches inconsistent heading levels, trailing whitespace, missing language hints, and 40+ other issues.",[29,317,319],{"id":318},"link-checking","Link Checking",[15,321,322,323,326,327,330],{},"Broken links erode trust. Use ",[209,324,325],{},"markdown-link-check"," or ",[209,328,329],{},"lychee"," in CI:",[267,332,334],{"className":269,"code":333,"language":271,"meta":272,"style":272},"- name: Check Links\n  run: npx markdown-link-check README.md\n",[209,335,336,347],{"__ignoreMap":272},[276,337,338,340,342,344],{"class":278,"line":279},[276,339,290],{"class":289},[276,341,294],{"class":293},[276,343,297],{"class":289},[276,345,346],{"class":300},"Check Links\n",[276,348,349,351,353],{"class":278,"line":286},[276,350,307],{"class":293},[276,352,297],{"class":289},[276,354,355],{"class":300},"npx markdown-link-check README.md\n",[29,357,359],{"id":358},"spell-checking","Spell Checking",[15,361,362,363,326,366,369],{},"Tools like ",[209,364,365],{},"cspell",[209,367,368],{},"vale"," catch typos and enforce style guidelines:",[267,371,373],{"className":269,"code":372,"language":271,"meta":272,"style":272},"- name: Spell Check\n  run: npx cspell \"**\u002F*.md\"\n",[209,374,375,386],{"__ignoreMap":272},[276,376,377,379,381,383],{"class":278,"line":279},[276,378,290],{"class":289},[276,380,294],{"class":293},[276,382,297],{"class":289},[276,384,385],{"class":300},"Spell Check\n",[276,387,388,390,392],{"class":278,"line":286},[276,389,307],{"class":293},[276,391,297],{"class":289},[276,393,394],{"class":300},"npx cspell \"**\u002F*.md\"\n",[15,396,397],{},"Run these checks on every pull request. Fixing issues in CI is infinitely cheaper than fixing them after publication.",[10,399,401],{"id":400},"export-formats-in-depth","Export Formats in Depth",[29,403,149],{"id":404},"html",[15,406,407],{},"Most Markdown workflows produce HTML as their primary output. The path is straightforward:",[409,410,411,425,428,431],"ol",{},[144,412,413,414,417,418,417,421,424],{},"Parse Markdown to HTML (via ",[209,415,416],{},"marked",", ",[209,419,420],{},"remark",[209,422,423],{},"markdown-it",")",[144,426,427],{},"Apply a CSS stylesheet for branding and layout",[144,429,430],{},"Inject syntax highlighting for code blocks (Prism, highlight.js)",[144,432,433],{},"Optionally add a table of contents from heading IDs",[15,435,436],{},"HTML output gives you maximum flexibility — deploy it anywhere, style it with any CSS framework, embed it in any CMS.",[29,438,155],{"id":439},"pdf",[15,441,442],{},"PDF generation typically routes through HTML first, then uses a headless browser:",[267,444,448],{"className":445,"code":446,"language":447,"meta":272,"style":272},"language-bash shiki shiki-themes github-light github-dark","# Using Puppeteer\nnpx puppeteer print docs\u002Findex.html output.pdf\n","bash",[209,449,450,455],{"__ignoreMap":272},[276,451,452],{"class":278,"line":279},[276,453,454],{"class":282},"# Using Puppeteer\n",[276,456,457,461,464,467,470],{"class":278,"line":286},[276,458,460],{"class":459},"sScJk","npx",[276,462,463],{"class":300}," puppeteer",[276,465,466],{"class":300}," print",[276,468,469],{"class":300}," docs\u002Findex.html",[276,471,472],{"class":300}," output.pdf\n",[15,474,475],{},"Pandoc offers a direct Markdown-to-PDF path via LaTeX, which produces publication-quality typography but requires a LaTeX installation.",[29,477,161],{"id":478},"docx",[15,480,481],{},"Pandoc converts Markdown to DOCX with one command:",[267,483,485],{"className":445,"code":484,"language":447,"meta":272,"style":272},"pandoc input.md -o output.docx\n",[209,486,487],{"__ignoreMap":272},[276,488,489,492,495,499],{"class":278,"line":279},[276,490,491],{"class":459},"pandoc",[276,493,494],{"class":300}," input.md",[276,496,498],{"class":497},"sj4cs"," -o",[276,500,501],{"class":300}," output.docx\n",[15,503,504],{},"Customize the output with a reference DOCX template that defines styles for headings, code blocks, and tables.",[29,506,167],{"id":507},"slides",[15,509,510],{},"Marp and Slidev turn Markdown into presentation slides:",[267,512,516],{"className":513,"code":514,"language":515,"meta":272,"style":272},"language-markdown shiki shiki-themes github-light github-dark","---\nmarp: true\n---\n\n# Project Overview\n\nKey metrics and goals\n\n---\n\n## Q4 Results\n\n- Revenue: $2.4M\n- Growth: 18% YoY\n","markdown",[209,517,518,523,528,532,539,545,550,556,561,566,571,577,582,588],{"__ignoreMap":272},[276,519,520],{"class":278,"line":279},[276,521,522],{},"---\n",[276,524,525],{"class":278,"line":286},[276,526,527],{},"marp: true\n",[276,529,530],{"class":278,"line":304},[276,531,522],{},[276,533,535],{"class":278,"line":534},4,[276,536,538],{"emptyLinePlaceholder":537},true,"\n",[276,540,542],{"class":278,"line":541},5,[276,543,544],{},"# Project Overview\n",[276,546,548],{"class":278,"line":547},6,[276,549,538],{"emptyLinePlaceholder":537},[276,551,553],{"class":278,"line":552},7,[276,554,555],{},"Key metrics and goals\n",[276,557,559],{"class":278,"line":558},8,[276,560,538],{"emptyLinePlaceholder":537},[276,562,564],{"class":278,"line":563},9,[276,565,522],{},[276,567,569],{"class":278,"line":568},10,[276,570,538],{"emptyLinePlaceholder":537},[276,572,574],{"class":278,"line":573},11,[276,575,576],{},"## Q4 Results\n",[276,578,580],{"class":278,"line":579},12,[276,581,538],{"emptyLinePlaceholder":537},[276,583,585],{"class":278,"line":584},13,[276,586,587],{},"- Revenue: $2.4M\n",[276,589,591],{"class":278,"line":590},14,[276,592,593],{},"- Growth: 18% YoY\n",[15,595,596],{},"Write once, present anywhere. Changes to content update the slides instantly — no more copy-pasting between tools.",[10,598,600],{"id":599},"team-collaboration-best-practices","Team Collaboration Best Practices",[15,602,603],{},"When multiple people write Markdown together, consistency becomes critical.",[29,605,607],{"id":606},"establish-a-style-guide","Establish a Style Guide",[15,609,610],{},"Define rules for:",[141,612,613,619,632,638,644],{},[144,614,615,618],{},[147,616,617],{},"Heading hierarchy"," — only one H1, no skipped levels",[144,620,621,624,625,326,628,631],{},[147,622,623],{},"List style"," — choose ",[209,626,627],{},"-",[209,629,630],{},"*"," and stick with it",[144,633,634,637],{},[147,635,636],{},"Code block hints"," — always specify the language",[144,639,640,643],{},[147,641,642],{},"Link style"," — inline vs. reference",[144,645,646,649,650,653,654,424],{},[147,647,648],{},"File naming"," — kebab-case (",[209,651,652],{},"api-guide.md",", not ",[209,655,656],{},"API Guide.md",[15,658,659,660,663],{},"Document these rules in a ",[209,661,662],{},"CONTRIBUTING.md"," file at the root of your repository.",[29,665,667],{"id":666},"use-templates","Use Templates",[15,669,670],{},"Create Markdown templates for recurring document types:",[141,672,673,679,685],{},[144,674,675,678],{},[147,676,677],{},"RFC template"," — context, proposal, trade-offs, decision",[144,680,681,684],{},[147,682,683],{},"README template"," — description, installation, usage, license",[144,686,687,690],{},[147,688,689],{},"Runbook template"," — symptoms, diagnosis, resolution, escalation",[15,692,693],{},"Templates reduce decision fatigue and keep documents consistent across authors.",[29,695,697],{"id":696},"automate-formatting","Automate Formatting",[15,699,700],{},"Let tools handle style so humans focus on content:",[141,702,703,709,714],{},[144,704,705,708],{},[147,706,707],{},"Prettier"," formats Markdown on save or commit",[144,710,711,713],{},[147,712,224],{}," flags violations before merge",[144,715,716,719],{},[147,717,718],{},"CI checks"," enforce rules consistently across the team",[15,721,722],{},"The goal: reviewers discuss substance, not syntax.",[10,724,726],{"id":725},"workflow-summary","Workflow Summary",[267,728,733],{"className":729,"code":731,"language":732},[730],"language-text","Write Markdown → Preview in real time → Commit to Git → CI lints & checks → Merge → Auto-export (HTML\u002FPDF\u002FDOCX) → Publish\n","text",[209,734,731],{"__ignoreMap":272},[15,736,737],{},"Each step automates what it can. Humans focus on writing. Machines handle formatting, validation, and distribution.",[10,739,741],{"id":740},"key-takeaways","Key Takeaways",[141,743,744,747,750,753,756,759],{},[144,745,746],{},"A solid Markdown workflow has three stages: edit, preview, export — automate each one",[144,748,749],{},"Git and Markdown are a natural pair; short paragraphs and reference links reduce merge conflicts",[144,751,752],{},"CI pipelines should lint Markdown, check links, and spell-check on every pull request",[144,754,755],{},"Export through HTML for flexibility; use Pandoc for PDF and DOCX; use Marp for slides",[144,757,758],{},"Team consistency comes from style guides, templates, and automated formatting — not policing",[144,760,761],{},"The fewer manual steps in your pipeline, the more time you spend on actual content",[10,763,765],{"id":764},"related-guides","Related Guides",[141,767,768,774,780],{},[144,769,770],{},[128,771,773],{"href":772},"\u002Fguides\u002Fmarkdown-preview-guide","Markdown Preview Guide",[144,775,776],{},[128,777,779],{"href":778},"\u002Fguides\u002Fgithub-flavored-markdown","GitHub Flavored Markdown",[144,781,782],{},[128,783,785],{"href":784},"\u002Fguides\u002Fmarkdown-syntax-guide","Markdown Syntax Guide",[10,787,789],{"id":788},"try-it-yourself","Try It Yourself",[15,791,792,793,795],{},"See the edit-preview pipeline in action. Open our free ",[128,794,131],{"href":130}," tool — write your Markdown on the left, watch the rendered output on the right, and iterate until your content is publication-ready.",[797,798,799],"style",{},"html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .s9eBZ, html code.shiki .s9eBZ{--shiki-default:#22863A;--shiki-dark:#85E89D}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}",{"title":272,"searchDepth":286,"depth":286,"links":801},[802,803,808,812,817,823,828,829,830,831],{"id":12,"depth":286,"text":13},{"id":23,"depth":286,"text":24,"children":804},[805,806,807],{"id":31,"depth":304,"text":32},{"id":119,"depth":304,"text":120},{"id":135,"depth":304,"text":136},{"id":180,"depth":286,"text":181,"children":809},[810,811],{"id":187,"depth":304,"text":188},{"id":229,"depth":304,"text":230},{"id":250,"depth":286,"text":251,"children":813},[814,815,816],{"id":257,"depth":304,"text":258},{"id":318,"depth":304,"text":319},{"id":358,"depth":304,"text":359},{"id":400,"depth":286,"text":401,"children":818},[819,820,821,822],{"id":404,"depth":304,"text":149},{"id":439,"depth":304,"text":155},{"id":478,"depth":304,"text":161},{"id":507,"depth":304,"text":167},{"id":599,"depth":286,"text":600,"children":824},[825,826,827],{"id":606,"depth":304,"text":607},{"id":666,"depth":304,"text":667},{"id":696,"depth":304,"text":697},{"id":725,"depth":286,"text":726},{"id":740,"depth":286,"text":741},{"id":764,"depth":286,"text":765},{"id":788,"depth":286,"text":789},"2026-05-28","Build an efficient Markdown writing workflow. Learn toolchains, version control, CI\u002FCD integration, export formats, and team collaboration tips.","md",{"immutable":537},"\u002Fguides\u002Fmarkdown-writing-workflow",{"title":5,"description":833},"guides\u002Fmarkdown-writing-workflow","65PiBKX5HRtkaOOibpPkJV4jCPWzTTLB5XvP705Q60g",1780401327514]