limedocs/limedocs-wiki-converter

Generate HTML & PDF documentation from you Github wiki or any other markdown-based wiki

Limedocs Wiki Converter

Limedocs Wiki Converter allows you to generate HTML & PDF documentation from you Github wiki or any other markdown-based wiki.

Prerequesites

• Node.js or io.js
• wkhtmltopdf (only necessary for pdf output format)

Installation

npm install -g limedocs-wiki-converter

Usage

Basic usage

# Clone you github wiki for example
git clone https://github.com/limedocs/limedocs-wiki-converter.wiki.git

# Convert your wiki
lwc ./imedocs-wiki-converter.wiki

Usage help

  Usage: lwc [options] <wiki-dir>

  Convert a wiki

  Options:

    -h, --help                   output usage information
    -V, --version                output the version number
    -f, --format <format>        Format to convert to. Either html, pdf, or all [default: html]
    -o, --output <output-dir>    Output dir [default: './']
    -t, --title <title>          Wiki title [default: Documentation]
    -d, --disable-inline-assets  Disable inlining of images, css and js in html document
    --toc <toc-file>             Wiki TOC file
    --toc-level <level>          Table of contents deep level [default: 3]
    --highlight-theme <theme>    Highlighter theme [default: darkula]
    --css <css-file>             Additional CSS file
    -v --verbose                 Verbose mode

Formats

HTML

Pages to be included in the documentation

By default, Limedocs Wiki Converter will check for the following files to use as a table of contents (TOC):

• _Toc.md
• _Sidebar.md (which is the default sidebar file on Github wikis)

When finding a TOC, lwc will only generate pages linked from this TOC.

Inlining

By default, the HTML output format will generate a single-page HTML document of you wiki, with all assets inlined, such as images, css, and javascript. So all you need to transfer documentation (to a collegue for example) is to send him/her this unique file.

You can disable this inlining feature by passing --disable-inline-assets (or -d) such as serveral files will be generated for each of images, css and javascript files.

Table of contents (TOC)

The TOC is rendered using a fixed div in the HTML documentation. You can use --toc-level to prevent the TOC div to overlap the body element.

PDF

Rendering

PDF rendering is done using wkhtmltopdf which should be available in your PATH. It simply renders (more or less) the HTML version of your doc in PDF.

Code highlighting

Code highlighting is rendered using highlight.js. You can customize the theme used by using the --highlight-theme option. By default, darkula theme is used.

limedocs-wiki-converter's Issues

Support for emphasized text less than 3 characters

Right now, _ab_ outputs literally _ab_ instead of ab, while _abc_ outputs (correctly) abc.

Accessing non-existent property 'padLevels' of module exports inside circular dependency

Although 5 md files are found the PDF is empty!

C:\Users\MartinHinshelwoodnkd\source\repos\aps\aps [git-reset +4 ~0 -5 !]> lwc -f pdf -toc .\Trainer-Guidance\_Toc.md -v .\Trainer-Guidance\
debug:   gwc launched with options format=pdf, output=./, title=-o, tocFile=Trainer-Guidance\_Toc.md, tocLevel=3, highlightTheme=darkula, userCssFile=null, verbose=true, disableInlineAssets=false, filename=documentation
(node:13148) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency
(Use `node --trace-warnings ...` to show where the warning was created)
debug:   Found 5 markdown files and 5 links pointing to them in TOC
debug:   Generating pdf: 0 pages to generate
info:    pdf file written: documentation.pdf
C:\Users\MartinHinshelwoodnkd\source\repos\aps\aps [git-reset +4 ~0 -5 !]>

Empty PDF output

HTML output is fine but pdf output is empty

$ date 
Thu Nov  8 13:35:35 CET 2018

$ sudo npm install -g limedocs-wiki-converter
npm WARN deprecated [email protected]: Potential REDOS vulnerability removed in v1.1.0
npm WARN deprecated [email protected]: Potential REDOS vulnerability fixed in v0.3.0
/usr/bin/lwc -> /usr/lib/node_modules/limedocs-wiki-converter/dist/cli/lwc.js
+ [email protected]

$ git clone https://github.com/aol/moloch.wiki.git

$ lwc -v -f pdf ./moloch.wiki
debug:   gwc launched with options format=pdf, output=./, title=Documentation , tocFile=null, tocLevel=3, highlightTheme=darkula, userCssFile=null, verbose=true, disableInlineAssets=false, filename=documentation
debug:   Found 17 markdown files and 17 links pointing to them in TOC
debug:   Generating pdf: 17 pages to generate

$  file documentation.pdf 
documentation.pdf: empty

$ wkhtmltopdf documentation.html test.pdf
Loading page (1/2)
Printing pages (2/2)                                               
Done                         

$ file test.pdf 
test.pdf: PDF document, version 1.4

$ lsb_release -a
No LSB modules are available.
Distributor ID:	Debian
Description:	Debian GNU/Linux 9.5 (stretch)
Release:	9.5
Codename:	stretch

$ nodejs --version
v10.13.0

$ wkhtmltopdf -V
wkhtmltopdf 0.12.3.2

Unicode in TOC

Then I use russian TOC in documentation it's works perfect in github, but broken during export. Also some files from TOC not importred to output html.

Unhandled rejection Error

How do I enable support for linked image downloads?

C:\Users\MartinHinshelwoodnkd\source\repos\APS.wiki [master ≡]> lwc -f pdf -v -d .\
debug:   gwc launched with options format=pdf, output=./, title=Documentation , tocFile=null, tocLevel=3, highlightTheme=darkula, userCssFile=null, verbose=true, disableInlineAssets=true, filename=documentation
(node:26120) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency
(Use `node --trace-warnings ...` to show where the warning was created)
debug:   Found 19 markdown files and 19 links pointing to them in TOC
Unhandled rejection Error: The file https://cloud.githubusercontent.com/assets/89504/25373965/ff6d88c0-299b-11e7-85c7-579f05deafb3.jpg was not found!
Please report this to https://github.com/markedjs/marked.
    at DataURI.encodeSync (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\datauri\lib\datauri\api.js:63:19)
    at DataURI (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\datauri\lib\datauri\module.js:29:37)
    at Renderer.mainRenderer.image (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\dist\markdown.js:47:48)
    at InlineLexer.outputLink (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\marked\lib\marked.js:738:21)
    at InlineLexer.output (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\marked\lib\marked.js:653:19)
    at Parser.tok (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\marked\lib\marked.js:1142:50)
    at Parser.parse (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\marked\lib\marked.js:1003:17)
    at Function.Parser.parse (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\marked\lib\marked.js:985:17)
    at marked (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\node_modules\marked\lib\marked.js:1322:19)
    at Markdown.convertMarkdownString (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\dist\markdown.js:94:14)
    at Markdown.convertMarkdownFile (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\dist\markdown.js:99:19)
    at LimedocsWikiConverter.<anonymous> (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\dist\limedocs-wiki-converter.js:87:43)
    at Array.forEach (<anonymous>)
    at LimedocsWikiConverter.computePages (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\dist\limedocs-wiki-converter.js:83:27)
    at LimedocsWikiConverter.getPages (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\dist\limedocs-wiki-converter.js:97:14)
    at PdfWriter.write (C:\Users\MartinHinshelwoodnkd\AppData\Roaming\npm\node_modules\limedocs-wiki-converter\dist\pdf-writer.js:43:27)
C:\Users\MartinHinshelwoodnkd\source\repos\APS.wiki [master ≡ +6 ~0 -0 !]>

Using pdf format for output throws an error

Using version: 0.1.12

Using lwc like this: lwc -f pdf ./MySoftware.wiki

Gives me this error:

      throw er; // Unhandled 'error' event
      ^

Error: read ECONNRESET
    at _errnoException (util.js:999:13)
    at Pipe.onread (net.js:629:25)```

HTML works fine. Any suggestions? Thank you so much

Unsupported .MD syntax

I try to convert https://github.com/NancyFx/Nancy.wiki.git
1 [[localfile]] unsupported. I replace manually [[url]] on [url](url)
2.i added manually alias c# for highlight .js
3. Not found pdf output file. Html file looks not very good (in opera and chrome)

No inlining of .gif

.gif inlining is not working as expected

$ sudo npm install -g limedocs-wiki-converter
npm WARN deprecated [email protected]: Potential REDOS vulnerability removed in v1.1.0
npm WARN deprecated [email protected]: Potential REDOS vulnerability fixed in v0.3.0
/usr/bin/lwc -> /usr/lib/node_modules/limedocs-wiki-converter/dist/cli/lwc.js
+ [email protected]

$ git clone https://github.com/aol/moloch.wiki.git

$ lwc -v ./moloch.wiki
debug:   gwc launched with options format=html, output=./, title=Documentation , tocFile=null, tocLevel=3, highlightTheme=darkula, userCssFile=null, verbose=true, disableInlineAssets=false, filename=documentation
debug:   Found 17 markdown files and 17 links pointing to them in TOC
debug:   Generating html: 17 pages to generate
info:    html file written: documentation.html
documentation.html

$ grep .gif documentation.html |tail -n 4
<p>[[SingleHostMoloch.gif]]</p>
<p>[[MultiHostMoloch.gif]]</p>
<p>[[HighTrafficMoloch.gif]]</p>
<p>[[MultiClusterMoloch.gif]]</p>

# Expected result : the 4 .gif should be inlined (see https://github.com/aol/moloch/wiki/Architecture#single-host ) 

$ lsb_release -a
No LSB modules are available.
Distributor ID:	Debian
Description:	Debian GNU/Linux 9.5 (stretch)
Release:	9.5
Codename:	stretch

$ nodejs --version
v10.13.0