git-wiki-to-html
v0.3.0
Published
Export github/git markdown based wiki repository to HTML based site with navigation
Downloads
1,186
Readme
git-wiki-to-html
Scope
Export a gihub.com wiki to a website.
Generate files required for a single page javascript application starting from the markdown files of a github.com Wiki repository. Beside the content .html files corespondent to each .md file, it will also generate a multi-level menu based on filenames.
Example
I have a Github Wiki with the following pages (created via the administration panel):
Overview.md
Migration:Migration from 3.x to 4.x.md
Migration:Migration from 4.x to 5.x.md
New Features:New Features in 4.x.md
New Features:New Features in 3.x.md
I want to run a command to transform the files to a list of HTML/json files required for a standalone website.
Menu
- Overview
- Migration ^
- Migration from 3.x to 4.x
- Migration from 4.x to 5.x
- New Features ^
- New Features in 4.x
- New Features in 3.x
Content (dinamically loaded on menu click)
{Overview.md content transformed to HTML}
Module Features
- generates a menu HTML (or json) file that can be loaded in a javascript single page application (customisable template)
- generates for each of the markup files a HTML correspondent (customisable template and parsing rules)
- transforms internal (wiki) links to clickable local links
- supports multi-language templates (ex: en:Overview.md / fr:Overview.md) with only one entry in meny
- it provides a template for markdown side menu - auto-generate the github.com Wiki sidemenu from a repository
Install
npm install -g git-wiki-to-html
Usage
Help and syntax:
git-wiki-to-html
If you get command not found check that your (npm bin -g) folder is in your system $PATH
Example from a github wiki repository
Real example starting from a public wiki repository: https://github.com/expressjs/express.wiki
git clone https://github.com/expressjs/express.wiki.git
mkdir express-website
# generates in dest folder .html files for each .md file and a menu with local links to them in index.html
git-wiki-to-html --src=express.wiki/ --dest=express-website/
# generates in the dest folder the menu and files for an Angular based application
git-wiki-to-html --src=express.wiki/ --dest=express-website/ --template=angular
cd express.wiki
# generates a _Sidebar.md file with
git-wiki-to-html --template=markdown
# commit and push your changes to origin to have a sidebar menu
git commit -m "Sidebar update for my wiki page"
git push master origin
Ex of result for above:
* [Home](./Home)
* [Application Patterns](./Application-Patterns)
* [ESON JSON Configuration](./ESON-JSON-Configuration)
* [Migrating from 2.x to 3.x](./Migrating-from-2.x-to-3.x)
* [Migrating from 3.x to 4.x](./Migrating-from-3.x-to-4.x)
* [New features in 3.x](./New-features-in-3.x)
* [New features in 4.x](./New-features-in-4.x)
* [README template](./README-template)
Customizing
Use --option=/path/to/my/options.json to override the parsing rules with custom ones
- menu - replace rules for generating the menu file
- rules (pre/post) - Regex rules to be applied before and after HTML transformation
- rules.order - Specify a custom order (default lexical) to the menu items
- rules.exclude - Specify a a list of items to be excluded (a category will match all subcategories)
- separator - provide a different separator
- prefixFiles - option to select only files starting with a prefix
- linkTemplate - define your local link template
- menuFile - replace the default filename for the menu file
- multilang - enable/disable menu parsing rules for locale prefixes
Source and target directory can be set using --src / --dest
A particular template can be used from default / angular / markdown
Implementation example
my Sales Activity - Online Help
Note: This application is build using this module and supports over 12 languages (Choose for example: French / Spanish, German to see how the content is displayed in a different language)