Welcome to md2html-action! This guide will help you quickly start converting Markdown files to beautiful, styled HTML using this powerful GitHub Action.
md2html-action is a GitHub Action that converts Markdown files to stunning HTML using Pandoc. It’s designed to work with pure vanilla Markdown - no special setup, frontmatter, or configuration required!
Before you begin, ensure you have:
Create .github/workflows/convert-docs.yml in your
repository:
name: Convert Markdown to HTML
on:
push:
paths: ["docs/**/*.md"]
pull_request:
paths: ["docs/**/*.md"]
jobs:
convert:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Convert Markdown to HTML
uses: CameronBrooks11/md2html-action@main
with:
source-dir: "docs" # Directory containing your .md files
output-dir: "html" # Where to save the HTML files
stylesheet: "technical" # Choose: default, minimal, academic, technical, blog, corporate
template: "default" # Choose: default, minimal, githubCreate a docs/ directory and add
docs/index.md:
# My Documentation
Welcome to my documentation site!
## Getting Started
This is a simple Markdown file that will be converted to beautiful HTML.
### Features
- Pure Markdown support
- No frontmatter required
- Automatic table of contents
- Responsive design
## Code Examples
Here's some Python code:
\```python
def hello_world():
print("Hello from md2html-action!")
\```
## Links
- [GitHub Repository](https://github.com/your-username/your-repo)
- [Documentation](https://your-username.github.io/your-repo/)Commit and push your changes:
git add .
git commit -m "Add md2html-action documentation"
git pushCheck the Actions tab in your GitHub repository
Watch as your Markdown is converted to stunning HTML!
md2html-action includes 6 professional themes:
| Theme | Best For | Description |
|---|---|---|
| 🎓 Academic | Research papers, theses | Traditional typography, scholarly formatting |
| 💻 Technical | API docs, developer guides | Modern tech company design with Inter fonts |
| 📝 Blog | Personal blogs, articles | Comfortable reading typography |
| 🏢 Corporate | Business docs, reports | Professional, authoritative styling |
| 🎨 Default | General documentation | Clean, balanced design |
| ⚡ Minimal | Simple sites | Lightweight, fast-loading |
To change themes, simply update the stylesheet parameter
in your workflow:
- uses: CameronBrooks11/md2html-action@main
with:
stylesheet: "academic" # Change this to any theme namemd2html-action works with any standard Markdown file. Here are the key elements:
# Main Title (H1)
## Section (H2)
### Subsection (H3)
#### Details (H4)Pro Tip: Headers automatically generate a table of contents!
**Bold text** for emphasis
_Italic text_ for subtle emphasis
`inline code` for technical terms
~~Strikethrough~~ for correctionsUnordered lists:
- First item
- Second item
- Nested item
- Another nested item
Ordered lists:
1. Step one
2. Step two
3. Step three
Task lists:
- [x] Completed task
- [ ] Pending task
- [ ] Future task[Link text](https://example.com)
[Internal link](other-page.md)
Use triple backticks with language specification:
```python
def example_function():
"""This is a Python function."""
return "Hello, World!"
```
```javascript
const greeting = (name) => {
return `Hello, ${name}!`;
};
```
```bash
# Shell commands
npm install
git commit -m "Update docs"
```| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Data 1 | Data 2 | Data 3 |
| Row 2 | More | Data |> This is a blockquote.
> It can span multiple lines.
>
> Perfect for highlighting important information!One of md2html-action’s greatest strengths is its support for pure vanilla Markdown:
# My Documentation
This is a simple Markdown file that requires no special setup!
## Features
- Pure Markdown support
- No frontmatter required
- Automatic title extraction from `# Heading`
- Table of contents generation
- Responsive design
## Code Example
\```python
def hello():
print("No configuration needed!")
\```
## Links
- [Another page](getting-started.md)
- [External link](https://github.com)While not required, you can add frontmatter for more control:
---
title: "Custom Page Title"
description: "SEO-friendly page description"
author: "Your Name"
date: "2024-01-01"
---
# Your Content Here
The frontmatter above is completely optional but gives you more control over metadata.your-repository/
├── docs/ # Your Markdown files
│ ├── index.md # Homepage
│ ├── getting-started.md # Getting started guide
│ ├── api/ # API documentation
│ │ ├── index.md
│ │ └── endpoints.md
│ ├── guides/ # User guides
│ │ ├── installation.md
│ │ └── configuration.md
│ └── media/ # Images and assets
│ ├── logo.png
│ └── screenshots/
├── .github/
│ └── workflows/
│ └── docs.yml # Your md2html-action workflow
└── README.mdgetting-started.md not start.md[Guide](guides/installation.md)All themes are fully responsive, but you can optimize for mobile:
<!-- Images automatically scale to container width -->| Feature | Mobile | Desktop |
| ------- | ------------- | ------------ |
| Layout | Single column | Multi-column |
| TOC | Collapsible | Sidebar |Now that you understand the basics:
📖 Read the Advanced Configuration Guide - Learn about custom templates, advanced Pandoc options, and deployment strategies
🎨 Explore the Demo Gallery - See all themes in action at the demo gallery
🔧 Customize Your Setup - Experiment with different themes and templates
📚 Check Real Examples - Browse the source code of this documentation for reference
Problem: Action not triggering
Solution: Check your workflow file paths and ensure
you’re pushing to the correct branch
Problem: Styles not applying
Solution: Verify the stylesheet name in your workflow
matches available themes
Problem: Images not showing
Solution: Use relative paths and ensure images are in
your source directory
Problem: TOC not generating
Solution: Make sure you’re using proper Markdown
headers (#, ##, ###)
Ready to dive deeper? Continue to Advanced Configuration for power-user features!