1 | <div class="hero" align="center">
|
2 |
|
3 | <img src="./assets/page.png">
|
4 |
|
5 | # sitedown
|
6 |
|
7 | Minimalist [Markdown](https://www.markdownguide.org/getting-started/)-based static site generator.
|
8 |
|
9 | [![npm][npm-image]][npm-url]
|
10 | [![build][build-image]][build-url]
|
11 | [![downloads][downloads-image]][npm-url]
|
12 |
|
13 | [npm-image]: https://img.shields.io/npm/v/sitedown.svg
|
14 | [npm-url]: https://www.npmjs.com/package/sitedown
|
15 | [build-image]: https://github.com/ungoldman/sitedown/actions/workflows/tests.yml/badge.svg
|
16 | [build-url]: https://github.com/ungoldman/sitedown/actions/workflows/tests.yml
|
17 | [downloads-image]: https://img.shields.io/npm/dm/sitedown.svg
|
18 |
|
19 | </div>
|
20 |
|
21 | ## Overview
|
22 |
|
23 | Sitedown turns a folder with Markdown files into a static HTML site.
|
24 |
|
25 | ```
|
26 | . build/
|
27 | ├─ README.md ==> ├─ index.html
|
28 | ├─ about.md ==> └─ about/
|
29 | │ │ └─ index.html
|
30 | │ │
|
31 | ├─ docs/ └─ docs/
|
32 | │ ├─ README.md ==> │ ├─ index.html
|
33 | │ └─ ref.md ==> │ └─ ref/
|
34 | │ │ └─ index.html
|
35 | │ │
|
36 | └─ assets/ └─ assets/
|
37 | └─ cat.jpg ==> └─ cat.jpg
|
38 | ```
|
39 |
|
40 | It takes all markdown files in the current folder (and subfolders) and generates a new site in the `build` directory.
|
41 |
|
42 | - Converts `README.md` files into indexes (`index.html`).
|
43 | - Creates directory indexes for pretty URLs (`CHANGELOG.md` => `changelog/index.html`).
|
44 | - Supports custom layouts (comes with a default `layout.html`).
|
45 | - Copies assets (defaults to copying over contents of `assets` folder).
|
46 | - Comes with a `dev` mode that starts a server and watches for changes for easy local development.
|
47 |
|
48 | Sitedown's [website](https://ungoldman.github.io/sitedown) was built with sitedown, so you know it's *for real*.
|
49 |
|
50 | Read the [Usage](#usage) section for a full overview of options and defaults.
|
51 |
|
52 | ## Install
|
53 |
|
54 | ```
|
55 | npm install sitedown
|
56 | ```
|
57 |
|
58 | ## Usage
|
59 |
|
60 | ### CLI
|
61 |
|
62 | ```console
|
63 | Usage: sitedown [source] [options]
|
64 |
|
65 | Example: sitedown . -b dist -l layout.html
|
66 |
|
67 | source path to source directory (default: current working directory)
|
68 | --build, -b path to build directory (default: "build")
|
69 | --pretty use directory indexes for pretty URLs (default: true)
|
70 | --el, -e css selector for target element (default: ".markdown-body")
|
71 | --layout, -l path to layout file
|
72 | --github-headings, -g add anchors to headings just like GitHub (default: false)
|
73 | --no-hljs-class don't add the hljs class to codeblocks (default: false)
|
74 | --silent, -s make less noise during build
|
75 | --watch, -w watch a directory or file (experimental)
|
76 | --dev, -d start development server (experimental) (default: false)
|
77 | --assets, -a assets folder to copy (default: "assets")
|
78 | --version, -v show version information
|
79 | --help, -h show help
|
80 | ```
|
81 |
|
82 | ### Node API
|
83 |
|
84 | ```js
|
85 | var sitedown = require('sitedown')
|
86 |
|
87 | var options = {
|
88 | source: '.', // path to source directory default: cwd
|
89 | build: 'build', // path to build directory default: 'build' in cwd
|
90 | pretty: true, // use directory indexes for pretty URLs default: true
|
91 | el: '.markdown-body', // css selector for target element default: '.markdown-body'
|
92 | layout: 'layout.html', // path to layout default: none
|
93 | githubHeadings: false, // add anchors to headings just like GitHub default: false
|
94 | noHljsClass: false, // don't add hljs class to codeblocks default: false
|
95 | silent: false // make less noise during build default: false
|
96 | }
|
97 |
|
98 | sitedown(options, function (err) {
|
99 | if (err) return console.error(err)
|
100 | console.log('success')
|
101 | })
|
102 | ```
|
103 |
|
104 | ### Layout
|
105 |
|
106 | 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.
|
107 |
|
108 | The default layout is:
|
109 |
|
110 | ```html
|
111 | <!DOCTYPE html>
|
112 | <html lang="en">
|
113 | <head>
|
114 | <meta charset="utf-8">
|
115 | <meta name="viewport" content="width=device-width, initial-scale=1">
|
116 | <title></title>
|
117 | <link rel="stylesheet" href="https://unpkg.com/style.css">
|
118 | </head>
|
119 | <body>
|
120 | <main class="markdown-body"></main>
|
121 | </body>
|
122 | </html>
|
123 | ```
|
124 |
|
125 | The default layout comes bundled with [`style.css`](https://ungoldman.github.io/style.css), a classless stylesheet for markdown documents.
|
126 |
|
127 | ### Directory indexes (pretty URLs)
|
128 |
|
129 | 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`).
|
130 |
|
131 | ### Links
|
132 |
|
133 | Relative links that point to markdown files (`$f.md`, `$f.markdown`) are rewritten as `$f/` to point to their `$f/index.html` equivalent.
|
134 |
|
135 | ## Contributing
|
136 |
|
137 | Contributions welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.
|
138 |
|
139 | ## License
|
140 |
|
141 | [ISC](LICENSE.md)
|
142 |
|
143 | Page image is from [emojipedia](https://emojipedia.org/page-facing-up/).
|