Category: Publishing

Plain text

This is the simplest way to do it.

Headings

The following HTML <h1>—<h6> elements represent six levels of section headings.

Example:

# This is an H1 - Do not use - Defined by title/description front matter
## This is an H2 - added to table of contents
### This is an H3 - added to table of contents
#### This is an H4
##### This is an H5 - label
###### This is an H6

Result:

This is an H2 - added to table of contents

This is an H3 - added to table of contents

This is an H4

This is an H5 - label

This is an H6

Paragraphs

Paragraphs are separated by empty lines. To create a new paragraph, press <return> twice.

Shortcodes available

Card shortcode

Draw the reader’s attention by separating information from the rest of the page. Convey meaning to this information by using colors implying success, info, warning, or danger and an appropriate icon.

Example front matter

---
title: Front matter
description: Front matter - YAML meta data
date: 2020-09-24
author: pCP Team
weight: 6
pcpver: "6.1.0"
toc: false
draft: false
hidden: false
categories:
- Publishing
tags:
- Front matter
---

Variables

Title

The title variable:

• is used in the left hand navigation menu.
• is used in the Previous/Next links at the bottom of the page.
• should be relatively brief. It is desireable for the the title to be a single line in the navigation menu. For example, use pCP instead of piCorePlayer.
• often the same or very similar to the file name.
• is used as the page title if description is not defined. It will be rendered as a Heading 1 at the top of the page.

Description

The description variable:

Hugo setup - Windows 10

See Installing Hugo.

Steps

Step 1 - Create directory structure

C:.
└── Hugo
    ├── bin
    └── pCP-docs

$ cd \

$ mkdir Hugo

$ cd Hugo

$ mkdir bin

$ mkdir pCP-docs

Step 2 - Add c:\Hugo\bin to $PATH

Edit the system environment variables.

Steps

Step 1 - Copy HTML source

• In the web page, select View source (ctrl+u in Edge)
• Copy the HTML code by:
  • Clicking on the HTML window to set focus.
  • Highlight all source (ctrl+a).
  • Copy highlighted source (ctrl+c).

Step 2 - Convert HTML to Markdown

• Open Turndown—click Turndown - HTML to Markdown.
  • Set Heading style to atx.
  • Set Bullet to -.
  • Set Code block style to fenced.
• Paste source in left HTML window (ctrl+v).
• Copy result from right MARKDOWN window (ctrl+a, ctrl+c).

Step 3 - Tidy up Markdown

• Paste into text editor (ctrl+c).
• Remove head and trailing rubbish.

More information

• Turndown - HTML to Markdown

Step 1 - Start Hugo

$ cd c:\Hugo\pCP-docs

$ hugo server

Optional:

Publish draft documents (draft: true)

$ hugo server -D

Publish future dated documents

$ hugo server -F

Force a republish of everything

$ hugo server --disableFastRender

Step 2 - Edit/add files under c:\Hugo\pCP-docs\content

C:.
├───bin
└───pCP-docs
    ├───archetypes
    ├───content
    │   ├───admin
    │   ├───components
    │   ├───downloads
    │   ├───faq
    │   ├───getting-started
    │   ├───how-to
    │   ├───information
    │   ├───projects
    │   └───releases
    ├───data
    ├───layouts
    ├───resources
    ├───static
    └───themes

Step 3 - View changes

Type http://localhost:1313/ into browser.

Adding a Download

Steps

Step 1. - Start Hugo

$ cd c:\Hugo\pCP-docs

$ hugo server

Step 2. - Edit pCP-docs\content\downloads\_index.md

Example of existing _index.md (Front matter - YAML formatting)

---
title: Downloads
description:
date: 2020-08-08   <-- edit
author: pCP Team
weight: 6
pcpver: "6.1.0"    <-- edit
toc: false
draft: false

download:
- pcpversion: "6.1.0"   --
  pcpdate: 2020-06-06     |  cut and paste 4 lines
  url: false              |  indentation 2 spaces (tabs not allowed)
  realtime: true        --
- pcpversion: "6.0.0"
  pcpdate: 2020-03-07
  url: false
  realtime: true
- pcpversion: "5.0.0"
  pcpdate: 2019-05-26
  url: false
  realtime: true



  ---

• edit date: —future dates wouldn’t publish
• edit pcpver:
• cut and paste 4 lines immediately below download:
• edit pcpversion:
• edit pcpdate:

Resulting _index.md

---
title: Downloads
description:
date: 2020-08-18     <- updated
author: pCP Team
weight: 6
pcpver: "7.0.0"      <- updated
toc: false
draft: false

download:
- pcpversion: "7.0.0"    <- new  
  pcpdate: 2020-08-18    <- new
  url: false             <- new
  realtime: true         <- new
- pcpversion: "6.1.0"
  pcpdate: 2020-06-06
  url: false
  realtime: true
- pcpversion: "6.0.0"
  pcpdate: 2020-03-07
  url: false
  realtime: true
- pcpversion: "5.0.0"
  pcpdate: 2019-05-26
  url: false
  realtime: true



---  

• Hugo uses template pCP-docs\themes\ace-documentation\layouts\downloads\list.html
• Hugo will detect changes to _index.md and will republish. Browser will auto update.

Adding a Release

Steps

Step 1. - Copy pCP-docs\content\releases\pcp6.1.0.md

$ cd c:\Hugo\pCP-docs\content\releases\