Overview
Sitedown turns a folder with Markdown files into a static HTML site.
. build/
ββ README.md ==> ββ index.html
ββ about.md ==> ββ about/
β β ββ index.html
β β
ββ docs/ ββ docs/
β ββ README.md ==> β ββ index.html
β ββ ref.md ==> β ββ ref/
β β ββ index.html
β β
ββ assets/ ββ assets/
ββ cat.jpg ==> ββ cat.jpg
It takes all markdown files in the current folder (and subfolders) and generates a new site in the build directory.
- Converts
README.mdfiles into indexes (index.html). - Creates directory indexes for pretty URLs (
CHANGELOG.md=>changelog/index.html). - Supports custom layouts (comes with a default
layout.html). - Copies assets (defaults to copying over contents of
assetsfolder). - Comes with a
devmode that starts a server and watches for changes for easy local development.
Sitedown's website was built with sitedown, so you know it's for real.
Read the Usage section for a full overview of options and defaults.
Install
npm install sitedown
Usage
CLI
Usage: sitedown [source] [options]
Example: sitedown . -b dist -l layout.html
source path to source directory (default: current working directory)
--build, -b path to build directory (default: "build")
--pretty use directory indexes for pretty URLs (default: true)
--el, -e css selector for target element (default: ".markdown-body")
--layout, -l path to layout file
--github-headings, -g add anchors to headings just like GitHub (default: false)
--no-hljs-class don't add the hljs class to codeblocks (default: false)
--silent, -s make less noise during build
--watch, -w watch a directory or file (experimental)
--dev, -d start development server (experimental) (default: false)
--assets, -a assets folder to copy (default: "assets")
--version, -v show version information
--help, -h show helpNode API
var sitedown = require('sitedown')
var options = {
source: '.', // path to source directory default: cwd
build: 'build', // path to build directory default: 'build' in cwd
pretty: true, // use directory indexes for pretty URLs default: true
el: '.markdown-body', // css selector for target element default: '.markdown-body'
layout: 'layout.html', // path to layout default: none
githubHeadings: false, // add anchors to headings just like GitHub default: false
noHljsClass: false, // don't add hljs class to codeblocks default: false
silent: false // make less noise during build default: false
}
sitedown(options, function (err) {
if (err) return console.error(err)
console.log('success')
})Layout
All files are wrapped in a layout.html file. Markdown content is appended to the first .markdown-body element, and the page title (<title> in <head>) is set to the text of the first h1 element.
The default layout is:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title></title>
<link rel="stylesheet" href="https://unpkg.com/style.css">
</head>
<body>
<main class="markdown-body"></main>
</body>
</html>The default layout comes bundled with style.css, a classless stylesheet for markdown documents.
Directory indexes (pretty URLs)
Markdown files ($f.md, $f.markdown) are lowercased and parsed into $f/index.html files. Directory indexes can be disabled with the pretty: false option. README.md files are always converted to directory indexes (index.html).
Links
Relative links that point to markdown files ($f.md, $f.markdown) are rewritten as $f/ to point to their $f/index.html equivalent.
Contributing
Contributions welcome! Please read the contributing guidelines first.
License
Page image is from emojipedia.