keyboardcowboy / topdown
Markdown Table of Contents Generator
Requires
- php: >=5.5.0
This package is not auto-updated.
Last update: 2024-10-26 19:37:54 UTC
README
Generate a Table of Contents for your markdown files.
https://github.com/KeyboardCowboy/TopDown
This was inspired by the GitHub wiki. Its usefulness is trumped by the the fact that the sidebar is in no way connected to the wiki pages. You can break a link by changing a page name. With TopDown you can generate a simple Table of Contents, for example the _Sidebar.md
file in GitHub, just by using a simple naming convention.
How it Works
-
Install this library.
-
Create a PHP file and include TopDown.php.
-
Tell TopDown where the files live and the name of the TOC file to create.
$sidebar = new TopDown('/path/to/files'); $sidebar->create('TableOfContents.md');
This will create the file /path/to/files/TableOfContents.md
With GitHub
GitHub wikis are their own repos. Check yours out to your local machine instead of editing the files in the UI. When you are done creating or editing your files, run TopDown and your sidebar is ready to go!
There is a subclass to make generating GitHub Wiki sidebars super simple.
-
Check out your wiki repo and
cd
into it. -
Run
composer require keyboardcowboy/topdown
-
Add a php file, for example
buildSidebar.php
to the repo then copy and paste this snippet:<?php require_once 'vendor/keyboardcowboy/topdown/TopDown.php'; $sidebar = new GitHubWikiSidebar(); $sidebar->create();
Now, simply run php buildSidebar.php
! That’s it!
File Names
TopDown relies on a simple naming convention to generate the hierarchy. By default a double-hyphen is used as the hierarchical separator, but you can tell TopDown to use any string as the separator. For example:
contributing.md
contributing--configuration.md
contributing--configuration--advanced.md
contributing--configuration--beginner.md
contributing--getting-started.md
contributing--giving-back.md
more.md
Would generate a table of contents like this:
- Contributing
- Configuration
- Advanced
- Beginner
- Getting Started
- Giving Back
- Configuration
- More
TopDown reads the files out of the given directory top down, which is generally alphabetically, so to rearrange items simply prefix them with a number.
contributing.md
contributing--1-getting-started.md
contributing--2-configuration.md
contributing--2-configuration--1-beginner.md
contributing--2-configuration--2-advanced.md
contributing--3-giving-back.md
more.md
File names that begin with a number then a period or hyphen will have that part trimmed off to generate the link name.
- Contributing
- Getting Started
- Configuration
- Beginner
- Advanced
- Giving Back
- More
Options
TopDown::title
string
: Set a custom title for the file. Defaults to ‘Table of Contents’
TopDown::separator
string
: Set a custom separator to determine hierarchy. Defaults to --
.
TopDown::format
int
: Set the list format. Defaults to TopDown::UNORDERED
.
TopDown::fileExt
bool
: Whether or not to build the links with the file extension. GitHub does not use the .md
file extensions on its wiki page urls.
TopDown::ignore
array
: An array of filenames to ignore.
TopDown::footer
string
: A custom file to use to generate the footer below the table of contents. Use FALSE
to disable the footer content.