Loppo has some command line options.
--dir or -d sets the document directory which keeps the original Markdown files. docs is the default directory.
$ loppo --dir my_docs
5 | --output or -o sets the output directory which keeps the generated documents. dist is the default directory.
$ loppo --output my_site
6 | --site or -s sets the site's name. Documents is the default.
$ loppo --site "My Documents"
7 | --theme or -t sets a site's theme. loppo-theme-oceandeep is the default.
$ loppo --theme oceandeep
8 | --id sets a site's ID (default is the dir name of the project).
--direction sets the document's character direction. ltr is the default. It also could be setted as rtl.
The option needs the support of the site theme.
--debug opens Loppo's debug mode.
--version or -v shows Loppo's version information.
--help gives Loppo's commandline usage.
示例：
loppo --dir docs --output dist
Loppo is an extremely easy static site generator of markdown documents. You get your site with only one command. Please visit demo.
Attention: Loppo is still in its very early stages. Use it in production at your own risk.
First of all, arrange your documents into the following structure.
|- myProject
5 | |- README.md
6 | |- docs
7 | |- page1.md
8 | |- page2.md
9 | |- ...
10 | Now, install Loppo.
$ npm install loppo -g
11 | Enter your project directory.
$ cd myProject
12 | Run the command.
$ loppo
13 | Now, Loppo will build the document site under dist sub-directory. After the building process, you could open the site in your browser.
$ open dist/index.html
14 | GPL v3
Loppo supports two git-style subcommands.
loppo server builds the document site at first, and thereafter launch a web server on 8080 port for dist sub-directory.
$ loppo server
5 | After running the comand, you could visit http://127.0.0.1:8080 in your browser.
This command is helpful for preview when you develop your documents.
loppo count will output statistic information of your documents.
$ loppo count
6 |
7 | [Files] 56
8 | [Lines] 8885
9 | [Words] 51555
10 | [Chars] 362931
11 | Attention, before using this command, chapters.yml must already be existed. Otherwise you will get an error.
loppo count has two options.
# output every markdown file's statistic information
12 | $ loppo count --detail
13 |
14 | # output a specified markdown file's statistic information
15 | # the file path should be same as the corresponding item in chapters.yml
16 | $ loppo count -f some.md
17 | loppo chapter will re-create chapters.yml and add new Markdown files into it.
Attention, the old chapters.yml will be deleted after running the command.
$ loppo chapter
18 |
19 | This command will delete your chapters.yml if existed.
20 | Are you sure to continue? （Y/N）
21 | If you want to skip the confirmation, use --force option.
$ loppo chapter --force
22 | Loppo provides some template variables used in templates.
They could be divided into two categories: site variables and page variables.
The site variables are the same within the whole site.
option.site is the site name (default is Documents).
option.id is the site id (default is the dir name of the project).
option.dir is the document directory of the repo.
option.chapters is an array which includes all .md files and directories in the docs directory.
[
5 | {'a.md': 'Title A'},
6 | {'dir1/': 'dir1'},
7 | {'dir1/b.md': 'Title B'}
8 | ]
9 | If the doc directory has nothing, option.chapters will be an empty array.
option.chaptersOrigin is just yet another form of option.chapters with different data structure.
[
10 | { origin: 'a.md', path: 'a.html', text: 'Title A', nextLevelBegins: false, currentLevelEnds: false },
11 | { origin: 'dir1/', path: 'dir1/index.html', text: 'dir1', nextLevelBegins: true, currentLevelEnds: false },
12 | { origin: 'dir1/b.md', path: 'dir1/b.html', text: 'Title B', nextLevelBegins: false, currentLevelEnds: true, currentLevelEndNum: 2}
13 | ]
14 | Fields
currentLevelEnds is trueoption.chapterList is a HTML string converted from option.chapters.
option.loppo_version is the version number of Loppo.
Page variables are different for every document page.
option.current_path is the relative path of current page, such like dir1/example.md.
For the index page of document directory, option.current_path is /.
option.content is the HTML markup of current page converted from markdown. It has three posibilities.
.md file, option.content is its markdown content.docs directory), option.content is the content of README.md under the project root directory (not docs directory)。If no README.md，option.content is an empty string.option.content is all .md files and sub-directories directly under it.option.isHomepage is a boolean value to indicate whether on not the current page is the homepage of the site.
option.page_title is the page name of a document page.
option.site.<h1> title of README.md. If not, it is option.site..md file, it is the <h1> title of the file. If not, it is the title in chapters.yml.option.previous_page_object is an object which represents the previous page of current page.
null.chapters.yml.For example, current page is b.md as following. Then option.previous_page is { 'b.md': 'Title B' }.
- a.md: Title A
15 | - b.md: Title B
16 | Attention, if current page is the first item of chapters.yml and is not index.md，option.previous_page will be { 'index.md': 'Home' }.
option.previousPageOrigin is yet another form of option.previous_page_object with different data structure.
{ origin: 'b.md', path: 'b.html', text: 'Title B' }
17 | option.previous_page is a HTML string converted from option.previous_page_object.
option.next_page_object is object which represents the next page of current page.
null.chapters.yml.For example, current page is a.md as following. Then option.next_page_object is { 'a.md': 'Title A' }.
- a.md: Title A
18 | - b.md: Title B
19 | option.nextPageOrigin is yet another form of option.next_page_object with different data structure.
{ origin: 'b.md', path: 'b.html', text: 'Title B' }
20 | option.next_page is a HTML string converted from option.next_page_object.
option.relative_root_path is the relative path to the root path for the current page.
For example, if the root path is / and the current page is dir1/a.md, option.relative_root_path is ../.
option.build_time is the time of building the current page, which is a JavaScript Date instance.
option.breadcrumbOrigin is an array containing the location information of current page.
For example, if current page is dir1/dir2/a.md, option.breadcrumb is the following.
[
21 | { path: 'index.html', text: 'Home' },
22 | { path: 'dir1/index.html', text: 'dir1' },
23 | { path: 'dir1/dir2/index.html', text: 'dir2' },
24 | { path: 'dir1/dir2/a.html', text: 'Title A' }
25 | ]
26 | option.breadcrumb is a HTML string which containing the location information of current page.
<div class="breadcrumb-area">
27 | <a href="index.html" class="breadcrumb-item" target="_blank">Home</a>
28 | <span class="breadcrumb-delimitor"> > </span>
29 | <a href="dir1/" class="breadcrumb-item" target="_blank">dir1</a>
30 | <!-- ... -->
31 | </div>
32 | option.toc is the table of content of current page.
This is an example.
\n'); 31 | t.end(); 32 | } 33 | ); 34 | 35 | test( 36 | test_title + 37 | 'special title', 38 | function (t) { 39 | const opt = { 40 | dir: 'docs', 41 | site: 'My Site', 42 | chapters: [ 43 | { 'dir1/': 'dir1' }, 44 | { 'dir1/a.md': 'Title A' }, 45 | { 'dir2/': 'dir2' }, 46 | { 'dir2/b.md': 'Title B' } 47 | ], 48 | content: '## HTML 文档的”标题“\n' 49 | }; 50 | const optionObj = markdownRender('dir1/a.md', opt); 51 | t.equal(optionObj.toc, 'console.log("hello world");\nHello World
', 24 | templates: {} 25 | }; 26 | 27 | opt.templates.page = _.template('<%= content %>'); 28 | 29 | writePage('/', opt); 30 | 31 | t.ok(fs.existsSync(path.join(TEST_PATH, opt.output, 'index.html'))); 32 | t.equal( 33 | fs.readFileSync(path.join(TEST_PATH, opt.output, 'index.html'), 'utf8'), 34 | 'Hello World
' 35 | ); 36 | t.end(); 37 | fs.removeSync(path.join(TEST_PATH, opt.output)); 38 | } 39 | ); 40 | -------------------------------------------------------------------------------- /utils/escapeTitle.js: -------------------------------------------------------------------------------- 1 | const { escape } = require('lodash'); 2 | 3 | function escapeTitle(chapters) { 4 | if (!chapters) return undefined; 5 | chapters.map(c => { 6 | for (let key in c) { 7 | c[key] = escape(c[key]); 8 | } 9 | return c; 10 | }); 11 | return chapters; 12 | } 13 | 14 | module.exports = escapeTitle; 15 | -------------------------------------------------------------------------------- /utils/findRootPosition.js: -------------------------------------------------------------------------------- 1 | function findRootPosition(root, optionObj) { 2 | for (let i = 0; i < optionObj.chapters.length; i += 1) { 3 | if (optionObj.chapters[i][root]) { 4 | return i; 5 | } 6 | } 7 | throw new Error('Cannot find the path in Chapters!'); 8 | } 9 | 10 | module.exports = findRootPosition; 11 | -------------------------------------------------------------------------------- /utils/isHomepage.js: -------------------------------------------------------------------------------- 1 | function isHomepage(root) { 2 | if (root === '/' || root === 'index.md') return true; 3 | return false; 4 | } 5 | 6 | module.exports = isHomepage; 7 | -------------------------------------------------------------------------------- /utils/makeBreadcrumb.js: -------------------------------------------------------------------------------- 1 | function makeBreadcrumb(root, optionObj) { 2 | const bcHTMLArr = []; 3 | optionObj.breadcrumbOrigin.forEach(function (c) { 4 | let bcPath = c.path; 5 | /* 6 | if (bcPath.substr(-3) === '.md') { 7 | bcPath = bcPath.substr(0, bcPath.length - 3) + '.html'; 8 | } else if (bcPath.substr(-1) === '/') { 9 | bcPath += 'index.html'; 10 | } 11 | */ 12 | const str = '' 16 | + c.text 17 | + ''; 18 | bcHTMLArr.push(str); 19 | }); 20 | let bcHTML = ''; 23 | optionObj.breadcrumb = bcHTML; 24 | return optionObj; 25 | } 26 | 27 | module.exports = makeBreadcrumb; 28 | -------------------------------------------------------------------------------- /utils/makeBreadcrumbOrigin.js: -------------------------------------------------------------------------------- 1 | const findRootPosition = require('./findRootPosition'); 2 | 3 | function transform(chapterObj) { 4 | let key = Object.keys(chapterObj)[0]; 5 | let value = chapterObj[key]; 6 | 7 | if (key.substr(-3).toLowerCase() === '.md') { 8 | key = key.substr(0, key.length - 3) + '.html'; 9 | } 10 | 11 | if (key.substr(-1) === '/') { 12 | key += 'index.html'; 13 | } 14 | 15 | return { 16 | path: key, 17 | text: value 18 | }; 19 | } 20 | 21 | function makeBreadcrumbOrigin(root, optionObj) { 22 | const breadcrumbArr = [transform({ 'index.md': 'Home' })]; 23 | if (root !== '/') { 24 | const pathArr = root.split('/'); 25 | let currentPath = ''; 26 | for (let i = 0; i < pathArr.length - 1; i += 1) { 27 | currentPath += pathArr[i] + '/'; 28 | for (let m = 0; m < optionObj.chapters.length; m += 1) { 29 | if (optionObj.chapters[m][currentPath]) { 30 | breadcrumbArr.push(transform(optionObj.chapters[m])); 31 | break; 32 | } 33 | } 34 | } 35 | } 36 | 37 | if (root[root.length - 1] !== '/') { 38 | if (root.substr(-8) === 'index.md') { 39 | breadcrumbArr.pop(); 40 | } 41 | const position = findRootPosition(root, optionObj); 42 | breadcrumbArr.push(transform(optionObj.chapters[position])); 43 | } 44 | optionObj.breadcrumbOrigin = breadcrumbArr; 45 | return optionObj; 46 | } 47 | 48 | module.exports = makeBreadcrumbOrigin; 49 | -------------------------------------------------------------------------------- /utils/makeChapterList.js: -------------------------------------------------------------------------------- 1 | function makeChapterList(root, optionObj) { 2 | let chapterArr = optionObj.chapters; 3 | if (!optionObj.chapters) { 4 | chapterArr = []; 5 | } 6 | let str = '