Markdown Site Generator
A markdown site generator which generates static sites, supporting the no-trailing-slash mode, and can be used to generate blog sites.
TO DO
- [ ] Parse markdown document metadata.
- [ ] Parse folder/index.json metadata.
Installation
Install via npm
globally:
sudo npm install markdown-site-generator --global
Install to your local markdown site locally:
npm install markdown-site-generator --save-dev
After installation, you will get the generate-md-site
command available.
Get Started
Run the generate-md-site --init My-Blogs
to generate a markdown site for test,
and you will follow the built-in instructions to get started.
Run the generate-md-site My-Blogs
to build your markdown site(, and then you may host the generated site).
Usage
Run the generate-md-site --help
to get available options and usage examples like shown following:
fisher@zb ~/workspace $ generate-md-site
› Please specify the target dir for your markdown site.
A markdown site generator which generates static sites, supporting the *no-trailing-slash* mode, and can be used to generate blog sites.
USAGE
$ generate-md-site [TARGET-DIR]
ARGUMENTS
TARGET-DIR the site/configs entrance to be resolved and parsed.
OPTIONS
-h, --help print the usage document for help.
-i, --init initialize a new or an existed markdown site with prompts and the default configures.
-n, --no-writing build markdown site without writing to disk.
-p, --print print out the resolved structure of your markdown site without building.
-s, --silent use the silent mode, with no output.
-t, --test test your configs and stat out the structure of your markdown site without building.
-v, --version print the version information.
-x, --verbose use the verbose mode, with rich output.
DESCRIPTION
The *Markdown Site Generator* supports sites in the following three different modes:
1. The **Dot HTML** Mode: In this mode, every markdown file is rendered directly to the corresponding HTML file.
2. The **Trailing Slash** Mode: This mode abandons the ending *.html* and appends a trailing slash to the URL.
3. The **No Trailing Slash** Mode: Site generated and hosted in the *no-trailing-slash* mode has no trailing slash in the URL.
EXAMPLES
$ generate-md-site . # build your markdown site and generate a static site.
$ generate-md-site --init . # initialize an existed markdown site with prompts and the default configures.
$ generate-md-site --init <site-name> # create a new markdown demo site with prompts and the default configures.
$ generate-md-site --test . # test configs without building site.
$ generate-md-site --print . # print the resolved site structure.
$ generate-md-site --no-writing . # build markdown site without writing to disk.
$ generate-md-site --no-cache . # build markdown site without cache( of static assets).
$ generate-md-site --version # print the version of the markdown site generator.
$ generate-md-site --help # print the help document of the markdown site generator.
Site Configures
The site configures may consist of the following fields:
The mark "
- [x]
" stands for required field while "- [ ]
" stands for optional field.
- [x]
title
- The site title.
- [x]
inputDir
- The root dir of your markdown site.
- [x]
outputDir
- The root dir of the generated site.
- [x]
mdPageTemplate
- The template(using the ejs engine) for the rendered markdown document.
Here is a demo of configurations:
// configs/index.js
'use strict';
const path = require('path');
// The selected configs of selected theme(github), which take cares of used templates and selected mode.
// Merge it into the site configures to make it work(, and existed configures may be overridden).
const configures = require('./github/dot-html-templates/configs');
// The default configs for the markdown site.
module.exports = Object.assign({
title: 'My Awesome Blogs',
inputDir: path.resolve(__dirname, '..'),
outputDir: path.resolve(__dirname, '../.site'),
// Filter out some files or folders.
nameFilters: [
(name) => name.startsWith('_reserve'),
(name) => ['backups', 'README.md', 'Drafts', 'logs'].includes(name),
],
nameConverter: (name) => name.toLowerCase(),
/* The following configures will be overridden by the configures of selected theme. */
/* Modify the selected configures directly to customize site's templates and mode. */
// The configures of the site building mode, which will be overridden by the selected mode.
// Generate site in the dot-html mode, if true, and !trailingSlash and !noTrailingSlash.
dotHTML: false,
// Generate site in the trailing-slash mode, if true and !noTrailingSlash.
trailingSlash: false,
// Generate site in the no-trailing-slash mode, if true.
noTrailingSlash: false,
// The configures of templates and assets used, which will be overridden by the selected templates.
assetsDir: path.resolve(__dirname, 'not-existed/assets'),
mdPageTemplate: path.resolve(__dirname, 'not-existed/templates/page.ejs'),
mdListTemplate: path.resolve(__dirname, 'not-existed/templates/list.ejs'),
}, configures);
Modes of the Markdown Site Generator
- The Dot HTML Mode: In this mode, every markdown file is rendered directly to the corresponding HTML file.
- The Trailing Slash Mode: This mode abandons the ending .html and appends a trailing slash to the URL.
- The No Trailing Slash Mode: Site generated and hosted in the no-trailing-slash mode has no trailing slash in the URL.
(Blog) Site Structure
The site structure of your original content and the generated.
-
A Demo Markdown Site
- Index.md
- README.md
- Test-File.md
- Test-Folder.md
- Test-Folder
- Index.md
- Test-Folder.md
- Test-File.md
- Test-File.any
- Rendering in the Dot HTML Mode and Host Normally
- index.html
/
- readme.html
/readme.html
- test-file.html
/test-file.html
- test-folder.html
/test-folder.html
- test-folder
- index.html
/test-folder/
- test-folder.html
/test-folder/test-folder.html
- test-file.html
/test-file.html
- test-file.any
/test-file.any
- index.html
- index.html
- Rendering in the Trailing Slash Mode and Host Normally
- index.html
/
- readme
- index.html
/readme/
- index.html
- test-file
- index.html
/test-file/
- index.html
- test-folder
- index.html
/test-folder/
- test-folder
- index.html
/test-folder/test-folder/
- index.html
- test-file
- index.html
/test-file/
- index.html
- test-file.any
/test-file.any
- index.html
- index.html
- Rendering in the No Trailing Slash Mode and Host in the No Trailing Slash Mode
- index.html
/
- readme
- readme.html
/readme
- readme.html
- test-file
- test-file.html
/test-file
- test-file.html
- test-folder
- test-folder.html
/test-folder
- the original
test-folder/test-folder.md
is rendered prior to thetest-folder/index.md
.
- the original
- test-file
- test-file.html
/test-folder/test-file
- test-file.html
- test-file.any
/test-folder/test-file.any
- test-folder.html
- index.html
References
- Hugo support for URLs without a trailing slash? - discourse.gohugo.io