A command-line tool to generate static HTML pages from Markdown files, applying various style themes.
- Convert Markdown files to HTML with stylish themes
- Create complete static blog sites with all themes
- Simple command-line interface for both single files and blogs
- Multiple pre-built retro and modern themes
- Configurable blog settings with front-matter support
- Automatic index and navigation generation for blogs
- Custom CSS and locale settings
- LaTeX math equation support (inline and display formats)
There are two ways to install stylemd:
If you want to use stylemd as a command-line tool anywhere on your system, install it globally via npm:
npm install -g @ddukbg/stylemdMake sure you have Node.js and npm installed.
If you want to contribute to the project or modify the code:
- Clone the repository:
git clone https://github.com/ddukbg/stylemd.git # Replace with your actual repo URL if different cd stylemd
- Install dependencies:
npm install
- Link the package: This allows you to run the
stylemdcommand locally using the cloned code.Now you can runnpm link
stylemdfrom any directory, and it will use the code in your clonedstylemdfolder.
StyleMD supports two main modes: single file conversion and blog mode.
Convert a single Markdown file to a styled HTML page:
stylemd <markdownFile> [options]Arguments:
<markdownFile>: Path to the input Markdown file (e.g.,notes.md,examples/input/example-default.md).
Options:
-t, --template <name>: Template name to use (default:default). See available themes above.-o, --output <file>: Output HTML file path (default:index.html).-h, --help: Display help for command.-V, --version: Output the version number.
Examples:
# Use the 'windows98' theme for 'mydoc.md' and output to 'mypage.html'
stylemd mydoc.md -t windows98 -o mypage.html
# Use the 'terminal' theme for an example file, output to the root
stylemd examples/input/example-terminal.md --template terminal --output example-output-terminal.html
# Use the default theme and output to 'index.html'
stylemd README.mdCreate and build a complete static blog site using any theme:
stylemd blog init <siteDir> [-T <template>]This creates a directory structure with everything needed for your blog:
<siteDir>/
├── content/ # Your blog posts as Markdown files
├── pages/ # Static pages (about, contact, etc.)
├── public/ # Output directory (generated HTML)
├── templates/ # Theme templates
│ └── <theme>/ # Selected theme (e.g., windows98)
│ ├── post.hbs # Post template (from original theme)
│ ├── page.hbs # Page template (from original theme)
│ └── index.hbs # Blog index template (includes post list)
└── stylemd.config.json # Blog configuration
Example:
stylemd blog init my-retro-blog -T windows98Create Markdown files in the appropriate directories:
- Blog posts: Add
.mdfiles to thecontent/directory - Static pages: Add
.mdfiles to thepages/directory
Each file can include front-matter at the top:
---
title: My First Blog Post
date: 2025-05-01
slug: first-post
draft: false
---
# This is my first post
Content goes here...Edit stylemd.config.json to customize your blog settings:
{
"siteTitle": "My Retro Blog",
"siteDescription": "A blog about retro computing",
"theme": "windows98",
"postsDir": "content",
"pagesDir": "pages",
"outputDir": "public",
"dateFormat": "YYYY-MM-DD",
"timeFormat": "HH:mm",
"locale": "en-US",
"pagination": {
"enabled": true,
"perPage": 5
},
"sortOrder": "newest-first",
"showDrafts": false,
"flatPosts": true,
"flatPages": true,
"author": {
"name": "Your Name",
"email": "your.email@example.com",
"avatar": "https://example.com/avatar.jpg"
},
"navigationLinks": [
{ "title": "About", "url": "about.html" },
{ "title": "Projects", "url": "projects.html" }
],
"socialLinks": [
{ "platform": "GitHub", "url": "https://github.com/yourusername" },
{ "platform": "Twitter", "url": "https://twitter.com/yourusername" }
],
"footerText": "© 2025 My Retro Blog",
"customCSS": ".my-custom-class { color: red; }"
}Key configuration options include theme selection, URL structure (flat or nested), pagination, author information, and custom CSS.
cd <siteDir>
stylemd blog buildThis generates your complete site in the public/ directory, ready for deployment.
You can also specify a custom output directory:
stylemd blog build --output distAfter building your blog, you can deploy it to any static hosting service:
# Example: Deploy to GitHub Pages
cp -r public/* docs/
git add docs
git commit -m "Update blog"
git push
# Example: Deploy to Netlify
# Just connect your GitHub repo to Netlify and set the publish directory to 'public'Here are the currently included themes (each with single page and blog mode support):
default: Clean, modern baseline style suitable for general documents. Page Preview | Blog Previewwindows98: Mimics the classic Windows 98 UI elements. Page Preview | Blog Previewterminal: Simulates an old-school terminal output with prompt and cursor. Page Preview | Blog Previewgeocities: A nostalgic, chaotic, and fun GeoCities-inspired theme. Page Preview | Blog Previewblueprint: Technical blueprint style with grid background and annotations. Page Preview | Blog Previewmacos-classic: Inspired by the look and feel of macOS Classic (System 7/8/9). Page Preview | Blog Previewamiga-workbench: Emulates the Amiga Workbench 1.x interface. Page Preview | Blog Previewmsdos: Text-mode interface resembling MS-DOS prompt andedit.com. Page Preview | Blog Previewc64: Commodore 64 BASIC screen style 9490 with pixel font. Page Preview | Blog Previewvim: Minimalist theme inspired by the Vim editor (Solarized Dark). Page Preview | Blog Previewretro-console: Monochrome retro game console/HUD interface (like Fallout's Pip-Boy). Page Preview | Blog Previewpixel-art: Retro RPG style with pixel font and UI window elements. Page Preview | Blog Previewy2k: Early 2000s web design aesthetic with Aqua elements. Page Preview | Blog Previewfrutiger-aero: Mid-2000s style with glossy, glassy, and nature-inspired elements. Page Preview | Blog Previewarea51: Dark, retro sci-fi/hacker theme with neon green text. Page Preview | Blog Previewheartland: Warm, cozy theme inspired by 90s personal/hobby sites. Page Preview | Blog Previewhollywood: Flashy 90s entertainment/fan site theme with gold and purple. Page Preview | Blog Previewatlantis: Mystical, dark fantasy theme inspired by sunken cities. Page Preview | Blog Preview
(All themes work for both single page conversions and full blog sites.)
stylemd/
├── bin/ # CLI script
├── templates/ # Theme templates (.hbs)
├── examples/
│ ├── input/ # Example Markdown files
│ └── output/ # Example generated HTML (Git ignored)
├── node_modules/ # Dependencies (Git ignored)
├── .gitignore # Files/folders ignored by Git
├── package.json
├── package-lock.json
└── README.md
Currently, stylemd only loads templates from its internal /templates directory. Using templates from custom external directories is not yet supported.
Contributions are welcome! If you'd like to add new themes, improve existing ones, fix bugs, or add features (like custom template directory support), please follow these steps:
- Fork the repository.
- Create a new branch for your feature or fix (
git checkout -b feature/my-new-theme). - Make your changes. Ensure new themes are added as
.hbsfiles in thetemplatesdirectory and consider adding a corresponding example.mdfile inexamples/input. - Test your changes locally.
- Commit your changes (
git commit -am 'Add some feature'). - Push to the branch (
git push origin feature/my-new-theme). - Create a new Pull Request.
Here are some features planned for future releases:
- Custom Template Directory: Support for loading themes from a user-specified directory (
--template-diroption). This will allow users to easily create and use their own themes without modifying the core package. - Watch Mode: A
--watchflag to automatically re-generate the HTML file when the source Markdown file is modified, providing a live preview experience during editing. - Directory Conversion: Ability to process an entire directory of Markdown files at once, converting each
.mdfile into a corresponding HTML file, potentially mirroring the input directory structure.
Contributions towards these features are welcome!
This project is licensed under the MIT License. See the LICENSE file for details.
StyleMD supports rendering LaTeX math equations using MathJax:
Inline equations can be written with single dollar signs: $E = mc^2$ renders as
Display equations can be written with double dollar signs:
$$ \frac{d}{dx}(x^n) = nx^{n-1} $$
Renders as: $$ \frac{d}{dx}(x^n) = nx^{n-1} $$
You can use all standard LaTeX math syntax in both single file mode and blog mode.