Livingdocs Documentation

Local Setup

This documentation is built using Hugo.

You can run it locally:

# install hugo
brew install hugo

# if you use WSL2 you need to additionaly install xdg-utils and setup a environment link to your prefered browser
# you simply can skip this step and skip the opener by 
sudo apt-get install -y xdg-utils

# install dependencies
npm install

# start the hugo dev server
npm start

If you use WSL2 and want to use opener (automatically starts the browser) you need to additionaly install xdg-utils and setup default browser (see below) OR skip this instructions, do not use the opener (npm start) and just start the server with 'exec hugo serve'

# install xdg-utils
brew install hugo

# link the default browser (opener can't handle blanks in paths)
ln -s /mnt/c/path/to/browser.exe /path/to/symlink

# define the default browser as variable
export BROWSER=~/path/to/symlink

When working with the lunr search code it can be useful to test the real production setup, due to the way we edit the search index for production:

# build the static site into `./public`
npm run build
# or the uncompressed version
npm run build:fast

# serve the `./public` directory
npm run start:production

When editing code you can run npm run build:fast in a separate terminal and then refresh the page to see the latest changes. This only takes 1-2 seconds.

Contribution Guide

Titles and Subtitles

Always start with h2 titles in your documents (h1 should only be used by templates for the page title). Then use h3 for subtitles.

Check your titles by reading the table of contents generated on the right side of the screen. The titles should make it clear what is to be expected in a section. E.g. avoid generic titles like 'Example'.

Shortcodes

{{< vimeo id="426279221" class="video-wrapper" >}}

{{< github "livingdocsIO/livingdocs-cli" "Livingdocs command line utility" >}}

{{< warning >}}The world is not a logic puzzle{{< /warning >}}

{{< added-in "release-2021-03" >}}

{{< deprecated-in "release-2021-03" >}}

{{< removed-in "release-2021-03" >}}

{{< release "release-2021-03" >}}

{{< feature-info "li-documents feature" "server" >}}

Note: Shortcode templates can be found in themes/hugo-docs/layouts/shortcodes.

Text

Always be brief and concise. Don't state opinions or use unnecessary adjectives. Or as Einstein puts it «as simple as possible but no simpler».

In the guides always state what a certain guide is trying to achieve. Be comprehensive, i.e. don't leave out stuff that would frustrate people following your guide.

Images

Images shouldn't be too high. Try to capture images with a 4/3 or similar ratio.

Screenshots

If you need to take a screenshot of a whole browser, either try to capture just the content without frame or just the specific window.

On a mac, press CMD+Shift+4 to capture a specific section on the screen. If you press Shift once if the screenshot tool is still open, you can capture a whole window.

Terminal

Please try to capture a nice segment. If possible try to embed the text in a text code block or use this website to generate an image.

Hugo Theme

Icons

Some icons were copied individually to themes/hugo-docs/assets/svg from https://primer.style/octicons/.

Document Headers

Every document has a header to control the behavior in the documentation. Below you will see an example:

---
title: Setup Notifications
linkTitle: Notifications
description: Configure notifications so users can watch documents
weight: 6
---

Properties

// a document will not be in search results
excludeFromSearch: true

// a document will not be rendered. Start your server with `npm run start -- -D` to see drafts for development
draft: true

// don't show the edit button for updating a document at github
renderEditButton: false

// don't show document teaser cards
renderSummaries: false

// don't show table of contents on the right side of the page
renderTOC: false

// helps search engine to find alternative words which is not in the body of the document
keywords:
  - myKeyword

Teaser Properties

Here you can see an example, how to define a document teaser

---
title: My title
linkTitle: This is my card title
bullets:
  - item 1 in your bullet list
  - item 2 in your bullet list
description: Describe the document
weight: 6
---

linkTitle - a document teaser card takes title as default, with linkTitle, you can overwrite the teaser title

Development

Debug Links in the documentation

npm install -g markdown-link-check
markdown-link-check SUMMARY.md -q