Wiki helpers

This action offers a number of helpers to help automate some of the laborious tasks across many files within a wiki. For example generating table of contents or backlinking references.

• Getting started
• Helpers
• How it works

Getting started

Template

To start off with you need to add as many or as few templating placeholders to your markdown files. Each of the helpers has a beginning and an end. It's identified via it's unique ID. Anything you put in-between the start and end will be replaced by auto generated content.

<!-- {{ID}} start [...optionName=optionValue] -->
{{auto generated}}
<!-- {{ID}} end -->

Templating options

| name | type | description | |:---------------|:-----------|:------------| | title | String | Overrides the title for this template. | | count | Number | Pass in a number to indicate how many list items are in this section. | | reduce | Boolean | true (default) adds additional space top and bottom false removes that extra spacing. | | templatePath | String | Path to your custom template for that specific section. | | type | String | accordion (default), contentOnly, titleContent | | open | Boolean | false (default) accordion is closed by default and hides its contents true Keeps it open on load. | | headingLevel | Number | 1-6 default is 5. Determines size and hierarchy of title. | | depthStart | Number | 1-6 default is 0. In table of contents it determines what level of hierarchy to begin building from. | | depthEnd | Number | 1-6 default is 3. In table of contents it sets how many levels to go down based on depthStart. | | group | String | Comma separated list of categories to list out. Default lists all. Remove dashes. |

Before

<!-- toc start open="true" -->
{{auto generated}}
<!-- toc end -->

---

<!-- toc start title="Content only TOC" type="contentOnly" -->
{{auto generated}}
<!-- toc end -->

---

<!-- toc start title="Title and List Table of Contents" type="titleContent" -->
{{auto generated}}
<!-- toc end -->

After

• Level 1
  • Level 2

---

• Level 1
  • Level 2

---

Title and List Table

• Level 1
  • Level 2

GitHub Actions

You can find this script in the GitHub Action Marketplace. Below are a two ways you can use this within your action workflow.

Usage

- name: Wiki Helpers
  uses: photodow/[email protected]

name: Edit wiki files
on:
  gollum:
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          repository: ${{github.repository}}.wiki
      - uses: photodow/[email protected]
        with:
          rootPath: ./
          buildPath: ./
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Github Actions - Wiki helpers

name: Repo to wiki
on:
  workflow_dispatch:
  push:
    branches:
    - main

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: photodow/[email protected]
        with:
          rootPath: "./samples"
          flattenDir: true
      - name: Upload Documentation to Wiki
        uses: joeizzard/action-wiki-sync@master
        with:
          username: ${{ github.event.pusher.name }}
          access_token: ${{ secrets.GITHUB_TOKEN }}
          wiki_folder: "./build"
          commit_username: ${{ github.event.pusher.name }}
          commit_email: ${{ github.event.pusher.email }}
          commit_message: 'action wiki sync: ${{ github.event.commits[0].message }}'

Run script

First install script

npm install wiki-helpers --save

Then run script

node node_modules/wiki-helpers/index.js [...optionName=optionValue]

Options

| name | type | description | |:----------------|:----------|:------------| | rootPath | String | ./ (default) sets path of markdown files. | | resetOnly | Boolean | false (default) runs and builds everything as expected. true resets all files to original state before the automated content was added. | | templatePath | String | Path to your custom template for everything. | | depsTitleHook | String | Title of your dependencies list. Defaults to Dependencies. Case sensitive. | | buildPath | String | ./build (default) Indicate a directory you would like the updated files to build into. | | flattenDir | Boolean | false (default) By default it maintains folder structure. true flattens all the files into a flat structure within the buildPath. |

Helpers

• Table of contents
• Used by
• Backlinks
• Category tagging
• Categories
• Dependency count

Table of contents

The table of content searches a document for all the markdown titles #, formats them into a list, and inserts into the placeholder code you position.

• Looks for markdown titles, and builds a table of contents list.
• Starts with level 3 titles (###)
• 3 levels depth applied

Usage

<!-- toc start -->
{{auto generated}}
<!-- toc end -->

Before

<!-- toc start -->
<!-- toc end -->

# Level 1
Proin venenatis sagittis placerat.

## Level 2
Duis id diam lectus.

### Level 3
Maecenas rutrum massa risus, et tempor ligula elementum eget.

#### Level 4
Maecenas felis nisl, scelerisque sit amet vestibulum at, porttitor ut felis.

##### Level 5
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

###### Level 6
Donec dictum eros interdum sagittis malesuada.

After

• Level 1
• Level 2
• Level 3
  • Level 4
    • Level 5
      • Level 6

Level 1

Proin venenatis sagittis placerat.

Level 2

Duis id diam lectus.

Level 3

Maecenas rutrum massa risus, et tempor ligula elementum eget.

Level 4

Maecenas felis nisl, scelerisque sit amet vestibulum at, porttitor ut felis.

Level 5

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Level 6

Donec dictum eros interdum sagittis malesuada.

Used by

The used by dependency tracking looks at a document to see what dependencies it has from a list provided by you. Based on this list it will begin to create used by references in other files found from that list.

• Starts collecting data once line containing Dependencies is found.
• Each proceeding line that starts with a - and contains [[a file name]] is collected.
• Stops looking after the list ends.

Usage

<!-- usedby start -->
{{auto generated}}
<!-- usedby end -->

Before

File-a.md

###### Dependencies
- [[File c]]

File-b.md

###### Dependencies
- [[File c]]

File-c.md

<!-- usedby start -->
<!-- usedby end -->

After

File-a.md

Dependencies

• File c

File-b.md

Dependencies

• File c

File-c.md

• File a
• File b

Backlinks

Backlinking takes a markdown file and looks for all the markdown files it's being linked back to from. It then compiles that list and inserts the references into the document's placeholder you position.

• Ignores dependency list references.
• Collecting [[this file name]] in other files.
• Collect 50 characters before and after reference.
• Highlight text using Text fragments

Usage

<!-- backlinks start -->
{{auto generated}}
<!-- backlinks end -->

Before

File-a.md

Lorem [[File b]] consectetur adipiscing elit.

<!-- backlinks start -->
<!-- backlinks end -->

File-b.md

Nullam sollicitudin dictum nulla, non iaculis diam sodales eu.

<!-- backlinks start -->
<!-- backlinks end -->

Praesent [[File a]] tristique nisl neque, eu dapibus arcu faucibus elementum. In eu tortor non ex laoreet elementum. Curabitur a mi tempus, egestas ipsum in, eleifend ipsum. Maecenas nisl odio, imperdiet eu magna sed, facilisis porta est. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.

After

File-a.md

Lorem File b consectetur adipiscing elit.

File a (2)

• Nullam sollicitudin dictum nulla, non iaculis File a diam sodales eu.
• Praesent File a tristique nisl neque, eu dapibus arcu faucibus ele...

File-b.md

Nullam sollicitudin dictum nulla, non iaculis File a diam sodales eu.

File a (1)

• Lorem File b consectetur adipiscing elit.

Praesent File a tristique nisl neque, eu dapibus arcu faucibus elementum. In eu tortor non ex laoreet elementum. Curabitur a mi tempus, egestas ipsum in, eleifend ipsum. Maecenas nisl odio, imperdiet eu magna sed, facilisis porta est. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.

Category tagging

The category tagging determines what category it belongs to based on the folder structure, and inserts into the document based on your placement.

• Categorized by folder names.
• Case sensitive folders.
• Replaces dashes with spaces.

Usage

_File-a.md

<!-- category start -->
{{auto generated}}
<!-- category end -->

Before

Folder structure

| Folder-a
|-- File-a.md

_File-a.md

<!-- category start -->
<!-- category end -->

Curabitur a mi tempus, egestas ipsum in, eleifend ipsum.

After

Folder a

Curabitur a mi tempus, egestas ipsum in, eleifend ipsum.

Categories

Categorizes the files by what folders they live in and generates a categorized navigation wherever you place the template placeholder.

• Categorized by folder names.
• Case sensitive folders.
• Replaces dashes with spaces.
• Lists out links by category.

Usage

_Sidebar.md

<!-- categories start -->
{{auto generated}}
<!-- categories end -->

Before

Folder structure

| Folder-a
|-- File-a.md
| Folder-B
|-- File-b.md
|-- File-c.md

_Sidebar.md

<!-- categories start -->
<!-- categories end -->

Curabitur a mi tempus, egestas ipsum in, eleifend ipsum.

After

_Sidebar.md

• File a

• File b
• File c

Curabitur a mi tempus, egestas ipsum in, eleifend ipsum.

Dependency count

After analyzing and collecting the dependencies this helper will count the dependencies and place it wherever you'd like.

• Counts dependencies after collecting.

Usage

<!-- dependencyCount start -->
{{auto generated}}
<!-- dependencyCount end -->

Before

File-a.md

###### Dependencies (<!-- dependencyCount start -->{{auto generated}}<!-- dependencyCount end -->)
- [[File b]]
- [[File c]]

After

File-a.md

Dependencies (2)

• File b
• File c

How it works

The wiki helpers is made up of two types of methods. Miners, and builders. These two different types of methods allows the script to list, read, and write the files only once while also trying to minimize the amount of loops to improve efficiency and performance.

Miners

Miners are functions in place to go through each file collect data, and build an organized data object of the wiki files and contents. Some examples might include tracking backlinks, or determining page category type.

| miners | description | |:--------|:------------| | reset| Resets document by removing all auto generated content so miners can start from a clean slate. | | collectDependencies | Scans all files to find list of dependencies and organizes them by dependency of this file and used by other files | | getBacklinks | Scans all files for references of a given file |

Builders

Builders take the mined data that has been organized, formats it into markdown and updates the file before writing.

| builder | description | |:--------|:------------| | usedby | Builds a used by list based on whether it's present in other files' dependency lists. | | backlinks | Builds a list of backlinks if referenced in other files. | toc | Scans the given file, and builds a table of contents for that file. | | category | Displays category type for that file. | | dependencyCount | Counts the number of dependencies and displays that number. |