Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/photodow/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.
https://github.com/photodow/wiki-helpers
dependencies github-actions javascript markdown npm-package
Last synced: about 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/photodow/wiki-helpers
- Owner: photodow
- Created: 2021-04-22T15:32:52.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2021-08-03T12:55:33.000Z (about 3 years ago)
- Last Synced: 2024-07-11T12:57:46.670Z (2 months ago)
- Topics: dependencies, github-actions, javascript, markdown, npm-package
- Language: JavaScript
- Homepage:
- Size: 359 KB
- Stars: 8
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-list - photodow/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. (JavaScript)
README
# 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](#Getting-started)
- [Helpers](#Helpers)
- [How it works](#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.
```markdown
{{auto generated}}
```
###### 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. |
Examples
###### Before
```markdown
{{auto generated}}
---
{{auto generated}}
---
{{auto generated}}
```
###### After
>
>
> Table of contents
>
> - [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](https://github.com/marketplace/actions/wiki-helpers). Below are a two ways you can use this within your action workflow.
#### Usage
```yml
- name: Wiki Helpers
uses: photodow/[email protected]
```
Edit wiki files directly
```yml
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
```
Edit in repo, and copy to wiki
```yml
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
```terminal
npm install wiki-helpers --save
```
###### Then run script
```terminal
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](#Table-of-contents)
- [Used by](#Used-by)
- [Backlinks](#Backlinks)
- [Category tagging](#Category-tagging)
- [Categories](#Categories)
- [Dependency count](#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
```markdown
{{auto generated}}
```
Examples
###### Before
```markdown
# 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
>
> Table of contents
>
> - [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
```markdown
{{auto generated}}
```
Examples
###### Before
`File-a.md`
```markdown
###### Dependencies
- [[File c]]
```
`File-b.md`
```markdown
###### Dependencies
- [[File c]]
```
`File-c.md`
```markdown
```
###### After
`File-a.md`
> ###### Dependencies
> - [File c](#)
`File-b.md`
> ###### Dependencies
> - [File c](#)
`File-c.md`
>
> Used by (2)
>
> - [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](https://web.dev/text-fragments/)
#### Usage
```markdown
{{auto generated}}
```
Examples
###### Before
`File-a.md`
```
Lorem [[File b]] consectetur adipiscing elit.
```
`File-b.md`
```
Nullam sollicitudin dictum nulla, non iaculis diam sodales eu.
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.
>
>
> References (2)
>
> **[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.
>
>
> References (1)
>
> **[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`
```markdown
{{auto generated}}
```
Examples
###### Before
`Folder structure`
```
| Folder-a
|-- File-a.md
```
`_File-a.md`
```markdown
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`
```markdown
{{auto generated}}
```
Examples
###### Before
`Folder structure`
```
| Folder-a
|-- File-a.md
| Folder-B
|-- File-b.md
|-- File-c.md
```
`_Sidebar.md`
```markdown
Curabitur a mi tempus, egestas ipsum in, eleifend ipsum.
```
###### After
`_Sidebar.md`
>
> Folder a (1)
>
> - [File a](#)
>
>
>
> Folder B (2)
>
> - [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
```markdown
{{auto generated}}
```
Examples
###### Before
`File-a.md`
```markdown
###### Dependencies ({{auto generated}})
- [[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`](#Used-by) | Builds a used by list based on whether it's present in other files' dependency lists. |
| [`backlinks`](#Backlinks) | Builds a list of backlinks if referenced in other files.
| [`toc`](#Table-of-contents) | Scans the given file, and builds a table of contents for that file. |
| [`category`](#category-tagging) | Displays category type for that file. |
| [`dependencyCount`](#Dependency-count) | Counts the number of dependencies and displays that number. |