{"id":24708788,"url":"https://github.com/keyboardcowboy/topdown","last_synced_at":"2026-05-04T20:31:33.658Z","repository":{"id":57006002,"uuid":"52914557","full_name":"KeyboardCowboy/TopDown","owner":"KeyboardCowboy","description":"Generate a Table of Contents from a directory of markdown files.","archived":false,"fork":false,"pushed_at":"2016-03-02T05:22:52.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-27T06:47:25.115Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KeyboardCowboy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-01T22:21:10.000Z","updated_at":"2024-03-31T14:44:32.000Z","dependencies_parsed_at":"2022-08-21T14:30:54.389Z","dependency_job_id":null,"html_url":"https://github.com/KeyboardCowboy/TopDown","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KeyboardCowboy%2FTopDown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KeyboardCowboy%2FTopDown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KeyboardCowboy%2FTopDown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KeyboardCowboy%2FTopDown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KeyboardCowboy","download_url":"https://codeload.github.com/KeyboardCowboy/TopDown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244917974,"owners_count":20531678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-27T06:47:31.984Z","updated_at":"2026-05-04T20:31:33.515Z","avatar_url":"https://github.com/KeyboardCowboy.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TopDown\n**Generate a Table of Contents for your markdown files.**\n\nhttps://github.com/KeyboardCowboy/TopDown\n\nThis 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.\n\n## How it Works\n1. Install this library.\n2. Create a PHP file and include TopDown.php.\n3. Tell TopDown where the files live and the name of the TOC file to create.\n\n\t\t$sidebar = new TopDown('/path/to/files');\n\t\t$sidebar-\u003ecreate('TableOfContents.md');\n\n\nThis will create the file `/path/to/files/TableOfContents.md`\n\n## With GitHub\nGitHub 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!\n\nThere is a subclass to make generating GitHub Wiki sidebars super simple.\n\n1. Check out your wiki repo and `cd` into it.\n2. Run `composer require keyboardcowboy/topdown`\n3. Add a php file, for example `buildSidebar.php` to the repo then copy and paste this snippet:\n\n\t\t\u003c?php\n\t\trequire_once 'vendor/keyboardcowboy/topdown/TopDown.php';\n\t\t\n\t\t$sidebar = new GitHubWikiSidebar();\n\t\t$sidebar-\u003ecreate();\n\nNow, simply run `php buildSidebar.php`!  That’s it!\n\n## File Names\nTopDown 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:\n\n\tcontributing.md\n\tcontributing--configuration.md\n\tcontributing--configuration--advanced.md\n\tcontributing--configuration--beginner.md\n\tcontributing--getting-started.md\n\tcontributing--giving-back.md\n\tmore.md\n\n\nWould generate a table of contents like this:\n\n- Contributing\n\t- Configuration\n\t\t- Advanced\n\t\t- Beginner\n\t- Getting Started\n\t- Giving Back\n- More\n\nTopDown reads the files out of the given directory top down, which is generally alphabetically, so to rearrange items simply prefix them with a number.\n\n\tcontributing.md\n\tcontributing--1-getting-started.md\n\tcontributing--2-configuration.md\n\tcontributing--2-configuration--1-beginner.md\n\tcontributing--2-configuration--2-advanced.md\n\tcontributing--3-giving-back.md\n\tmore.md\n\nFile names that begin with a number then a period or hyphen will have that part trimmed off to generate the link name.\n\n- Contributing\n\t- Getting Started\n\t- Configuration\n\t\t- Beginner\n\t\t- Advanced\n\t- Giving Back\n- More\n\n## Options\n\n`TopDown::title` *string*\n: Set a custom title for the file.  Defaults to ‘Table of Contents’\n\n`TopDown::separator` *string*\n: Set a custom separator to determine hierarchy.  Defaults to `--`.\n\n`TopDown::format` *int*\n: Set the list format.  Defaults to `TopDown::UNORDERED`.\n\n`TopDown::fileExt` *bool*\n: Whether or not to build the links with the file extension. GitHub does not use the `.md` file extensions on its wiki page urls.\n\n`TopDown::ignore` *array*\n: An array of filenames to ignore.\n\n`TopDown::footer` *string*\n: A custom file to use to generate the footer below the table of contents.  Use `FALSE` to disable the footer content.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeyboardcowboy%2Ftopdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeyboardcowboy%2Ftopdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeyboardcowboy%2Ftopdown/lists"}