Skip to content

Commit 4b40e08

Browse files
per1234per1234
committed
Add table of contents to documentation
It will be helpful to the reader to be able to get an overview of the documentation content and quickly navigate to the section of interest. The table of contents are automatically generated using the markdown-toc tool. Because it can be easy to forget to update the table of contents when the documentation content is changed, I have added a CI workflow to check for missed updates to readme ToC. On every push or pull request that affects the repository's documentation, it will check whether the table of contents matches the content.
1 parent 2d79e0e commit 4b40e08

File tree

3 files changed

+100
-0
lines changed

3 files changed

+100
-0
lines changed

‎.github/workflows/check-toc.yml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Check ToC
2+
3+
# See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows
4+
on:
5+
push:
6+
paths:
7+
- ".github/workflows/check-toc.yml"
8+
- "README.md"
9+
- "FAQ.md"
10+
pull_request:
11+
paths:
12+
- ".github/workflows/check-toc.yml"
13+
- "README.md"
14+
- "FAQ.md"
15+
workflow_dispatch:
16+
repository_dispatch:
17+
18+
jobs:
19+
check:
20+
name: ${{ matrix.file.name }}
21+
runs-on: ubuntu-latest
22+
23+
strategy:
24+
fail-fast: false
25+
26+
matrix:
27+
file:
28+
- name: README.md
29+
# Max ToC depth, for use with the markdown-toc --maxdepth flag.
30+
maxdepth: 4
31+
- name: FAQ.md
32+
maxdepth: 3
33+
34+
steps:
35+
- name: Checkout repository
36+
uses: actions/checkout@v2
37+
38+
- name: Get week number for use in cache key
39+
id: get-date
40+
run: |
41+
echo "::set-output name=week-number::$(date --utc '+%V')"
42+
43+
- name: Load dependencies cache
44+
uses: actions/cache@v2
45+
with:
46+
path: ~/.npm
47+
key: ${{ runner.os }}-node-markdown-toc-${{ steps.get-date.outputs.week-number }}
48+
restore-keys: |
49+
${{ runner.os }}-node-markdown-toc-
50+
51+
- name: Install markdown-toc
52+
run: sudo npm install --global markdown-toc
53+
54+
- name: Rebuild ToC
55+
run: markdown-toc --bullets=- --maxdepth=${{ matrix.file.maxdepth }} -i "${{ github.workspace }}/${{ matrix.file.name }}"
56+
57+
- name: Check ToC
58+
run: git diff --color --exit-code

‎FAQ.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,32 @@
11
# Arduino Library Manager FAQ
22

3+
## Table of Contents
4+
5+
<!-- toc -->
6+
7+
- [General](#general)
8+
- [What is the Arduino Library Manager?](#what-is-the-arduino-library-manager)
9+
- [How is the Library Manager index generated?](#how-is-the-library-manager-index-generated)
10+
- [Submission](#submission)
11+
- [How can I add my library to Library Manager?](#how-can-i-add-my-library-to-library-manager)
12+
- [What are the requirements for a library to be added to Library Manager?](#what-are-the-requirements-for-a-library-to-be-added-to-library-manager)
13+
- [Updates](#updates)
14+
- [How can I publish a new release once my library is in the list?](#how-can-i-publish-a-new-release-once-my-library-is-in-the-list)
15+
- [What are the requirements for publishing new releases of libraries already in the Library Manager list?](#what-are-the-requirements-for-publishing-new-releases-of-libraries-already-in-the-library-manager-list)
16+
- [Why aren't releases of my library being picked up by Library Manager?](#why-arent-releases-of-my-library-being-picked-up-by-library-manager)
17+
- [I did something wrong! How can I change or unpublish an already published library?](#i-did-something-wrong-how-can-i-change-or-unpublish-an-already-published-library)
18+
- [How can I change my library's name?](#how-can-i-change-my-librarys-name)
19+
- [Limitations](#limitations)
20+
- [Is my Git repository OK?](#is-my-git-repository-ok)
21+
- [Are Git submodules supported?](#are-git-submodules-supported)
22+
- [Usage](#usage)
23+
- [Can I add my own URL with my own library index?](#can-i-add-my-own-url-with-my-own-library-index)
24+
- [When I install a library that I know depends on another library, will this other library be installed as well?](#when-i-install-a-library-that-i-know-depends-on-another-library-will-this-other-library-be-installed-as-well)
25+
- [Can I install multiple versions of one library and use the proper one in my sketches?](#can-i-install-multiple-versions-of-one-library-and-use-the-proper-one-in-my-sketches)
26+
- [How can I remove a library I installed via Library Manager?](#how-can-i-remove-a-library-i-installed-via-library-manager)
27+
28+
<!-- tocstop -->
29+
330
## General
431

532
### What is the Arduino Library Manager?

‎README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,21 @@
33
This repository contains the list of libraries in the
44
[Arduino Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) index.
55

6+
## Table of Contents
7+
8+
<!-- toc -->
9+
10+
- [Frequently asked questions](#frequently-asked-questions)
11+
- [Adding a library to Library Manager](#adding-a-library-to-library-manager)
12+
- [Instructions](#instructions)
13+
- [If the problem is with the pull request:](#if-the-problem-is-with-the-pull-request)
14+
- [If the problem is with the library:](#if-the-problem-is-with-the-library)
15+
- [Changing the URL of a library already in Library Manager](#changing-the-url-of-a-library-already-in-library-manager)
16+
- [Removing the URL of a library already in Library Manager](#removing-the-url-of-a-library-already-in-library-manager)
17+
- [Report a problem with Library Manager](#report-a-problem-with-library-manager)
18+
19+
<!-- tocstop -->
20+
621
## Frequently asked questions
722

823
For more information about Arduino Library Manager and how the index is maintained, please see [the FAQ](FAQ.md).

0 commit comments

Comments
 (0)