Overcoming Challenges In Using Jekyll For Documentation Projects

Jekyll Conf 2016

Created by Tom Johnson

Reasons for discontent with tech writer tools

  • No HATs for Mac
  • CMSs cost $$$$
  • DITA too restrictive
  • Tired of WYSIWYG interfaces for content
  • Infrastructure for WordPress too cumbersome
  • Tech writer world too distanced from engineering
  • Tech pubs lags behind web innovation

"Blogging like a hacker"

"On Sunday, October 19th, I sat down in my San Francisco apartment with a glass of apple cider and a clear mind. After a period of reflection, I had an idea. While I'm not specifically trained as an author of prose, I am trained as an author of code. What would happen if I approached blogging from a software development perspective? What would that look like?"
Blogging like a hacker, Tom Preston-Werner, co-founder of Github
What would happen if we approached technical writing from a software development perspective?

Writing tech docs like a hacker

File format: Text files
Authoring: Text editor
Advanced logic Liquid
Collaboration: Git
Versioning: Git
Building: Jekyll

Using Jekyll for tech writing: My journey

Designing the Site?

Solution: Bootstrap

  • Turns out theming is easy
  • Easy to clone any existing site
  • Use Bootstrap for framework
More details »

Conditional filtering?

Solution: Liquid

{% if site.audience="administrators" %}
show this to administrators
{% elsif site.audience="analysts" %}
show this to analysts
{% endif %}
More details »

Multiple outputs?

Solution: Multiple config files

  • Separate config files for each variant
  • Each config file has various properties
    (audience, platform, product, version)
  • Create scripts that compile build commands
More details »

Environment workflows

Solution: Relative URLs

  • No permalinks
  • All markdown files stored in root directory
  • No need to configure url or baseurl properties
More details »

Multi-level navigation menu?

Solution: YAML + Navgoco

  • Store menu items in YAML file
  • "for" loop in HTML layout parses through YAML
  • Navgoco component handles other aspects (expand/collapse, cookie, accordion)
More details »

Alerts: Notes, tips, cautions?

Solution: Includes with Parameters

  • Store note code as include
  • Pass parameters with include code

// create the note.html include:

Note: {{include.content}}
//use it like this: {% include note.html content="My note content goes here ..." %}
More details »

Avoiding broken links?

Solution: YAML-based links

  • Iterate through TOC to create YAML file to get link names
  • Store urls.yml in _data folder
  • Reference links like this: {{site.data.urls.myfile.link}}
More details »

PDF output?

Solution: Prince XML

  • Iterate through sidebar menu to get list of links
  • Feed the list of links to Prince XML
  • Store command in shell script
More details »

Re-use across projects?

Solution: Single project for writers

  • All writers work in same project
  • Each project stored in its own subfolder
  • Still use relative links (redirect index.html in root to project home)
  • Put common content in non-excluded directory
  • Exclude other directories in each project's config file
More details »

Version control workflows?

Solution: Learn the needed workflow

  • Focus only on necessary Git commands
  • Coordinate more among team members
  • Avoid simultaneously editing the same page
  • Look regularly at commit logs


Solution: Stick with Core Jekyll

  • Avoid plugins or overly complicated code
  • Have all writers work in same project
  • Stop changing processes/code each month
  • Establish standards and provide training


Solution: Swiftype or Algolia

  • Implementation requires UX skills
  • More difficult if content isn't public
  • Never got around to implementing


Solution: Separate projects

  • Separate out UI strings into data file
  • Send out Markdown files for translation
  • Create new project with translated files


Solution: Involve Engineering

  • Recognize that IAM is an entire discipline
  • Simple implementations like onelogin.com aren't cheap
  • Push back on impossible requirements
  • Dynamically pull from AWS S3
  • Last resort: Salesforce site.com solution

Analogy with first telephone

Bell and an early model of the telephone
More details »

Documentation theme
for Jekyll

  • Newer theme: Single output, multiple sidebars (Github repo)
  • Older theme: Multiple outputs, one sidebar (Github repo)


Tom Johnson