Markdown is a popular format with developers for creating quick and easy documentation for software projects. Its utility is clear on sites such as GitHub where simple instructions and formatted code samples can be viewed directly in Markdown without additional styling, or as styled output within a web browser. This works well for small jobs, but how does Markdown scale when attempting to author something larger, more complex, and to a standard that a commercial product demands?
In this presentation, we will describe the process used to convert user documentation developed in Microsoft Word into an online documentation site using Pandoc, Python, and Gitbook and discuss some of the issues that the author faced along the way.
Presented at Write the Docs Perth, March 21, 2018.
Moving from word to the web via git book and markdown adam j limbert
1. MOVING FROM WORD TO THEMOVING FROM WORD TO THE
WEB VIA GITBOOK ANDWEB VIA GITBOOK AND
MARKDOWNMARKDOWN
BY ADAM J LIMBERTBY ADAM J LIMBERT
2. OBJECTIVESOBJECTIVES
Convert product documentation developed in
Microso Word to a website
Minimize rework (do it quickly)
Learn something new
Use existing tools (do not reinvent the wheel)
Use open source and free (or low cost) tools
Didn't want to buy into a proprietary framework
3. AN EXAMPLE TOOLCHAIN FOR CONVERSION...AN EXAMPLE TOOLCHAIN FOR CONVERSION...
1. Convert MS Word to Markdown using Pandoc
2. Edit and restructure resulting Markdown to suit
GitBook
Editing by hand
Topic-chunking using Python
Styling
3. Generate HTML and PDF
4. Consider the result, change tooling as needed
4. TOPIC-BASED WEBSITE WITH GITBOOKTOPIC-BASED WEBSITE WITH GITBOOK
Final Result: CProf User's Guide
9. PANDOC: WHAT IS IT?PANDOC: WHAT IS IT?
Open source document converter
Free so ware, released under the GPL
Copyright John MacFarlane
Many formats supported
10. CONVERTING FROM MS WORD TO GITHUB-FLAVOREDCONVERTING FROM MS WORD TO GITHUB-FLAVORED
MARKDOWN (GFM)MARKDOWN (GFM)
1. Download and install .
2. Open a command prompt/shell (e.g. Powershell in Win
3. Execute the following command (replacing input.docx
Microso Word document of your choice):
Pandoc
pandoc -f docx -t markdown_github --extract-media=./ -o README
11. Parameter Function
-f docx Input format is MS Word docx
-t
markdown_github
Desired output format is
Github-flavored Markdown
--extract-media=./ Extract images from document
and store in current directory
-o README.md Output file name (containing
the Markdown)
pandoc -f docx -t markdown_github --extract-media=./ -o README.md input.do
15. MARKDOWN: WHAT IS IT?MARKDOWN: WHAT IS IT?
Markdown is a popular format with developers for
creating quick and easy documentation for so ware
projects. Its utility is clear on sites such as GitHub
where simple instructions and formatted code
samples can be viewed directly in Markdown without
additional styling, or as styled output within a web
browser.
16. HISTORYHISTORY
A faster way to generate HTML - a kind of
shorthand
Philosophy: Markdown syntax should be as easy
to read as possible (without further processing)
Many different flavours have emerged:
Markdown Extra, MultiMarkdown, Pandoc
Markdown, CommonMark, GitHub-flavored
Markdown (GFM)
: MIME type text/markdown
John Gruber - 2004
RFC 7763
17. WHO'S USING MARKDOWN?WHO'S USING MARKDOWN?
GitHub (GFM)
Atlassian Bitbucket
Reddit
Diaspora
Stack Exchange
OpenStreetMap
SourceForge
(the framework used to create this
presentation)
Reveal.js
19. GITHUB-FLAVORED MARKDOWN: HEADINGSGITHUB-FLAVORED MARKDOWN: HEADINGS
Mark Meaning
# Title Heading Level 1
## Title Heading Level 2
### Title Heading Level 3
#### Title Heading Level 4
##### Title Heading Level 5
###### Title Heading Level 6
20. GITHUB-FLAVORED MARKDOWN: GENERALGITHUB-FLAVORED MARKDOWN: GENERAL
FORMATTINGFORMATTING
Mark Meaning
Text Paragraph text
*Text* or _Text_ Italics
**Text** or __Text__ Bold
~~Text~~ Strikethrough
> Quote Quoted text (indent)
``Code`` Inline code
```Code``` Code block (fenced)
22. GITHUB-FLAVORED MARKDOWN: MEDIA AND LINKSGITHUB-FLAVORED MARKDOWN: MEDIA AND LINKS
Mark Meaning
![Alternate text]
(path/image.jpg)
Image with alt
text
[Link text](URI) Link
23. LIMITATIONS?LIMITATIONS?
Simplistic tables
No underline (no direct mapping to HTML)
Final rendering relies on spacing/positioning, not
end tags - sensitive to indentation errors and
superfluous line breaks
If you can't do it in Markdown, you can (must) fall
back to HTML and CSS
Once you fall back to HTML, you are "stuck". You can't
nest Markdown inside the HTML.
24. EDITING MARKDOWNEDITING MARKDOWN
Any plain text editor...
...but an editor with a Markdown previewer is better
with
What you see is not always what you get!
Atom Markdown Preview
GitBook Editor
Demo: Interactive Markdown cheat sheet in
Observable
26. OVERVIEWOVERVIEW
is a new way of analyzing problems in CICS by
exposing the intrinsic value of the CICS internal trace.
Time to value is very quick for the following reasons:
CProf requires no changes to CICS itself. It requires
no exits, agents or resource definitions. CICS is
unaware of CProf activity, and is completely
unaffected by it.
CProf jobs operate at arm’s length to CICS. It is a
lightweight, low overhead solution.
CProf
28. GITBOOK: WHAT IS IT?GITBOOK: WHAT IS IT?
1. JavaScript library that parses Markdown to produce
a web-based book (HTML/CSS/JS)
On but moved to
2. A for books created with
GitBook
Github private repository
hosting environment
29. GETTING STARTEDGETTING STARTED
1. Get .
2. Install .
3. Open a command prompt/shell (e.g. Powershell).
4. To set up an initial project type:
NPM
GitBook
gitbook init
30. GITBOOK: INITIAL PROJECT PARTSGITBOOK: INITIAL PROJECT PARTS
Part Purpose
README.md The first topic in your book
SUMMARY.md The table of contents of your book
31. QUICK TESTQUICK TEST
1. In a shell, type:
The book is built and placed in the _book directory.
2. Browse index.html in the _book directory, or
serve the files up as you like (gitbook serve).
gitbook build
32. BRINGING IN YOUR SOURCE MATERIALBRINGING IN YOUR SOURCE MATERIAL
1. Copy your MS Word-based README.md into the
project directory (overwriting the default
README.md).
2. Repeat the build process (gitbook build) and
then browse the index.html file.
36. RESTRUCTURING THE README.MDRESTRUCTURING THE README.MD
1. Split up README.md into a set of topic-based files
2. Add those topic files to SUMMARY.md
Option A: Do it by hand (fine for small jobs)
Option B: Script it (e.g. Python)
37. SUMMARY.MD FORSUMMARY.MD FOR WWW.CPROF.COMWWW.CPROF.COM
### What is CProf?
* [Feature overview](README.md)
* [Multiple trace capture modes](txc_multiple_trace_captur
* [Import CICS auxiliary trace data sets and dump files](t
* [Enterprise-wide data capture and control](txc_enterpris
* [Measurement across the application lifecycle](txc_measu
* [A complete understanding of your CICS application](txc_
* [Minimum operating requirements](txc_minimum_operating_requi
* [About this document](txc_about_this_document.md)
### Initial Setup
* [Getting started](txc_getting_started.md)
* [Before you begin](txc_before_you_begin.md)
38. CONFIGURING YOUR BOOKCONFIGURING YOUR BOOK
Add to the directory.
Book configuration in JSON format
Title, author, etc.
Book plugins
book.json
42. TO INSTALL GITBOOK PLUGINSTO INSTALL GITBOOK PLUGINS
1. From the shell, type gitbook install.
2. Rebuild the project (gitbook build).
43. THEMES AND TEMPLATINGTHEMES AND TEMPLATING
Content references (if you dare)
Conditionals
Raw HTML (no Markdown processing)
Create your own theme plug-in
Gitbook default theme
{% include "./media/cprof-configure.md" %}
{% if output.name == "website" %}
Some text that only relates to the website version of the do
{% endif %}
{% raw %}
insert your HTML here
{% endraw %}
48. GITBOOK: BUILDING A PDFGITBOOK: BUILDING A PDF
1. Install .
2. In a shell, type:
3. Open the PDF in Adobe Acrobat
Calibre
gitbook pdf ./ ./mybook.pdf
More here
49. LIMITATIONS?LIMITATIONS?
No page numbers in table of contents: Unresolved,
unassigned issues and
Essentially unprintable in this state
Use ? Other problems arise.
What about ?
523 (Nov 2014) 1223 (April
2016)
WKHTMLTOPDF
Prince XML
51. MARKDOWN AND DITAMARKDOWN AND DITA
Authoring with Markdown in Jekyll versus Authoring
with DITA in OxygenXML
Simplifying DITA authoring by using a Markdown to
HTML to DITA workflow
Why You Shouldn’t Use “Markdown” for
Documentation
52. WEBSITE GENERATION USING MARKDOWNWEBSITE GENERATION USING MARKDOWN
and its companion
- Facebook Open
Source
- Wiki system used by the
GitHub web hosting system
Doesn't use Markdown but worth mentioning:
Is GitBook still alive? Is this
project dead?
Getting started with Docusaurus
Gollum: A Git-bsed Wiki
What is Jekyll, exactly?
HTMLBook
