https://github.com/keyboardcowboy/topdown
Generate a Table of Contents from a directory of markdown files.
https://github.com/keyboardcowboy/topdown
Last synced: about 1 month ago
JSON representation
Generate a Table of Contents from a directory of markdown files.
- Host: GitHub
- URL: https://github.com/keyboardcowboy/topdown
- Owner: KeyboardCowboy
- Created: 2016-03-01T22:21:10.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2016-03-02T05:22:52.000Z (over 10 years ago)
- Last Synced: 2025-01-27T06:47:25.115Z (over 1 year ago)
- Language: PHP
- Homepage:
- Size: 18.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# TopDown
**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
1. Install this library.
2. Create a PHP file and include TopDown.php.
3. 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.
1. Check out your wiki repo and `cd` into it.
2. Run `composer require keyboardcowboy/topdown`
3. Add a php file, for example `buildSidebar.php` to the repo then copy and paste this snippet:
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
- 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.