A plain project to generate static website from markdown.
This project provides a naive way to generate static html files from markdown, the robustness is still questionable.
npm installThere are two parts. The template theme and the documentations style.
npm run devAnd you are good to modify the src/index.less, src/index.ts and templates/template.html.
It's not so smart when you change the template.html file, the browser won't refresh. But the file does recompile, aka, rebuild.
Markdown style can be modified in src/mark.less. In case you do want to change the synatx style, the quickest way is to copy the them you like from here. (I use highlight.js for highlighting code),
Once you have sort out the frame theme, you can put your markdown file in the directory src/docs like this.
src/docs
├── doc1
| ├── static -> static images such as jpg, png, and svg.
| ├── config.json -> the menu tree and other configuration
| ├── chapter1.md
| ├── chapter2.md
| └── chapter3.md
|
├── doc2
| ├── static -> static images such as jpg, png, and svg.
| ├── config.json -> the menu tree and other configuration
| ├── chapter1.md
| ├── chapter2.md
| └── chapter3.md
|
...
Each directory in src/docs will create one static html file, and you can config them using config.js, example.
{
"title": "iOS 文档",
"filename": "ios.html",
"menus": [
{
"label": "概述",
"children": [
{
"label": "第一章",
"markdown": "chapter1"
}
]
},
{
"label": "第二章",
"markdown": "chapter2"
}
]
}Currently the template supports one-level-sub-menu, so some menu-item has a property children which is an array.
The markdown property is used for retrieve markdown file it the same directory, without extension. And that's why the markdown files are flattened in the above file tree.
As for images, just put them in the static under the same directory, refered by relative path.
Files under
staticdirectory would be copied todist/staticuntouched. More on this later.
Also, you could specify the deployUrl property in the package.json, which behaves like publicPath in webpack but for relative path in markdown files, useful images.
npm run buildThe output directory is dist under the root. Run npm run serve to check out.
The generated html files are put in the server root directory, along with static directory. This is why we put static images beside the markdown files.
# sugar for short check out
# equivalent `npm run build && npm run serve`
npm run build:serveThere is a property templateParameters in html-webpack-plugin, which helps to inject some string values into the template file.
// html-webpack-plugin
const htmlPlugins = new HtmlWebpackPlugin({
template: 'path/to/template.html',
templateParameters: {
title: 'new title',
content: 'new content',
footer: '<footer>this is an html footer</footer>'
}
});<!-- template -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title><%= title%></title>
</head>
<body>
<section class="content">
<%= content %>
</section>
<section class="footer">
<%= footer %>
</section>
</body>
</html>
<!-- output -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>new title</title>
</head>
<body>
<section class="content">
new content
</section>
<section class="footer">
<footer>this is an html footer</footer>
</section>
</body>
</html>This helps to generate output html files dynamically.
I choose marked for parsing markdown files, which return a string. Perfect, isn't it?
Althought the original markedjs is powerful enough to handle most usage cases, it doesn't support:
-
image size configuration, such as
or. -
baseUrlapplied on raw html tags, such as<img src="path/to/image.png">.
I tweak a little bit to the original project, here are the changes, which is the markdown parser used in this project. You can choose either one as long as that meets your requirement.