@single-page-markdown-website/frontend v0.0.25
Create a nice single-page website from one or more Markdown files
Features
- Zero configuration
- Render a table of contents, shortcuts to the top-level sections, and custom links
- Include the contents of other files using a special syntax
- Responsive
- Dark mode support
Quick start
Requires Node.js.
$ npx single-page-markdown-website '*.md' --open
The above command does the following:
- Concatenates the given globs of Markdown files (
'*.md'
) and renders the result as a single-page website tobuild/index.html
. - Copies any local image file referenced in the Markdown to
build/images
. - Opens the rendered page in your default web browser.
Configuration
Configuration is via the "single-page-markdown-website"
key of your package.json
file.
Single-Page Markdown Website works without configuration out of the box; all configuration options are optional.
{
"single-page-markdown-website": {
"baseUrl": "https://yuanqing.github.io/single-page-markdown-website/",
"title": "Single-Page Markdown Website",
"description": "Create a nice single-page website from one or more Markdown files",
"toc": true,
"sections": true,
"links": [
{
"text": "GitHub",
"url": "https://github.com/yuanqing/single-page-markdown-website"
}
],
"socialMediaPreviewImage": "media/share.png"
}
}
"baseUrl"
(string
)
The base URL of the single-page website.
"title"
(string
)
The title of the page.
- Defaults to
packageJson.name
"description"
(string
)
The meta
description of the page.
- Defaults to
packageJson.description
"toc"
(boolean
)
Whether to render a Table of Contents.
- Defaults to
true
"sections"
(boolean
)
Whether to render section shortcuts in the menu.
- Defaults to
true
Sections are the level-one headers (#
) in the Markdown. If there is only one level-one header, then sections are the level-two headers (#
).
"links"
(Array<{ text: string, url: string }>
)
A list of links to add to the menu.
- Defaults to
[{ text: 'GitHub', url: packageJson.homepage }]
"socialMediaPreviewImage"
(string
)
The URL or file path of the social media preview image to use for the website.
Tips
Including files
Use the following syntax to include the entire contents of a local file foo.md
in your Markdown:
./foo.md
Note that an empty line is required immediately before and after the file path.
- If the
./
prefix is used, then the file path is resolved relative to the current Markdown file. - If the
/
prefix is used, then the file path is resolved relative to the current working directory (ie.process.cwd()
).
You can also specify a glob to include multiple files:
./bar/*.md
Deploying to GitHub Pages
Deploy your single-page website to GitHub Pages via one of the following two ways:
Commit the
./build
directory and push your changes. Then, set the./build
directory as the publishing source in your GitHub repository settings.Use the
gh-pages
CLI to deploy the./build
directory to thegh-pages
branch:$ npx gh-pages --dist build
Then, set the
gh-pages
branch as the publishing source in your GitHub repository settings.
CLI
Create a nice single-page website from one or more Markdown files.
Usage:
$ single-page-markdown-website <files> [options]
Arguments:
<files> One or more globs of Markdown files. Defaults to 'README.md'.
Options:
-h, --help Print this message.
-p, --open Whether to open the generated page in the default web
browser. Defaults to 'false'.
-o, --output Set the output directory. Defaults to './build'.
-v, --version Print the version.
-w, --watch Whether to watch for changes and regenerate the page.
Defaults to 'false'.
Examples:
$ single-page-markdown-website
$ single-page-markdown-website '*.md'
$ single-page-markdown-website --open
$ single-page-markdown-website --output dist
$ single-page-markdown-website --watch
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago