Md To HTML

md-to-html

Overview

Convert markdown files into self-contained HTML documents by wrapping them in a Quarto (.qmd) file with the preferred YAML header, then rendering with quarto render.

Process

1. Identify the source markdown

• Locate the .md file in the working directory
• Read the file content to determine an appropriate title for the YAML header

2. Create the .qmd file

• Use the same filename with .qmd extension (hyphens, not underscores)
• Apply this YAML header, replacing the title to match the document:

---
title: "Document Title Here"
author: "Badran Elshenawy"
date: today
format:
  html:
    theme: darkly
    toc: true
    toc-depth: 3
    code-fold: show
    code-tools: true
    embed-resources: true
    self-contained: true
    title-block-banner: true
---

3. Run md-format on the source

Before copying content into the .qmd, invoke the md-format skill on the source .md file to catch and fix any formatting issues (e.g. bullet lists missing a blank line before them that would collapse horizontally in the rendered output). Apply all fixes to the source before proceeding.

4. Preserve the writing

• Copy all markdown content below the YAML header unchanged (after md-format fixes have been applied)
• Do not convert prose to bullet points or alter structure — this skill preserves content as-is
• The writing-qmd-scientific skill governs QMD authoring conventions; this skill is only for conversion

6. Fix line breaks

• Consecutive bold metadata lines (e.g. **Date:**, **Presenter:**) need a trailing \ to render on separate lines in Quarto
• Add \ at the end of each such line except the last

7. Render

quarto render filename.qmd

• Output is a self-contained .html file in the same directory

Naming Convention

• Use hyphens (-) not underscores (_) in filenames
• If the source .md uses underscores, rename to hyphens for both .qmd and .html
• See naming-conventions for the full rule

Common Mistakes