{"id":50749966,"url":"https://github.com/danjdewhurst/docs-toc-generator","last_synced_at":"2026-06-11T00:31:04.002Z","repository":{"id":325808148,"uuid":"1102456645","full_name":"danjdewhurst/docs-toc-generator","owner":"danjdewhurst","description":"A fast, efficient bash script that automatically generates table of contents for documentation files with smart content extraction and metadata","archived":false,"fork":false,"pushed_at":"2025-11-23T14:07:52.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-23T15:21:35.771Z","etag":null,"topics":["automation","bash","cli","docs-generator","documentation","markdown","shell-script","table-of-contents","toc"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danjdewhurst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-23T13:54:19.000Z","updated_at":"2025-11-23T14:07:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danjdewhurst/docs-toc-generator","commit_stats":null,"previous_names":["danjdewhurst/docs-toc-generator"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/danjdewhurst/docs-toc-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjdewhurst%2Fdocs-toc-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjdewhurst%2Fdocs-toc-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjdewhurst%2Fdocs-toc-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjdewhurst%2Fdocs-toc-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danjdewhurst","download_url":"https://codeload.github.com/danjdewhurst/docs-toc-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjdewhurst%2Fdocs-toc-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34177445,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["automation","bash","cli","docs-generator","documentation","markdown","shell-script","table-of-contents","toc"],"created_at":"2026-06-11T00:31:03.270Z","updated_at":"2026-06-11T00:31:03.976Z","avatar_url":"https://github.com/danjdewhurst.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Documentation ToC Generator\n\nA fast, efficient bash script that automatically generates a table of contents for your documentation files with smart content extraction and metadata.\n\n[![Test Suite](https://github.com/danjdewhurst/docs-toc-generator/actions/workflows/test.yml/badge.svg)](https://github.com/danjdewhurst/docs-toc-generator/actions/workflows/test.yml)\n[![Tests](https://img.shields.io/badge/tests-148%20passing-brightgreen)](tests/)\n[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](tests/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Bash](https://img.shields.io/badge/bash-3.2%2B-blue.svg)](https://www.gnu.org/software/bash/)\n\n## Features\n\n- **Smart Content Extraction**: Automatically extracts headings and meaningful snippets from markdown files\n- **Flexible Directory Scanning**: Specify any directory to scan, not just `docs/`\n- **Multiple Output Modes**:\n  - **Full Mode**: Rich output with snippets, file sizes, and modification dates\n  - **Simple Mode**: Clean, minimal list of files and titles\n  - **No-Snippets Mode**: Faster processing by skipping content extraction\n- **Advanced Filtering**:\n  - Include/exclude patterns for fine-grained file selection\n  - Support for multiple patterns per filter\n- **Flexible Grouping**:\n  - Group by directory (default)\n  - Group by file type/extension\n  - No grouping (flat list)\n- **Multiple Sorting Options**: Sort by name, date, or size\n- **Depth Control**: Limit directory traversal depth\n- **Customizable**:\n  - Custom ToC title\n  - Configurable snippet length\n  - Quiet mode for scripting\n- **Cross-Platform**: Compatible with Bash 3.2+ (works on macOS and Linux)\n- **Fast Performance**: Single-pass file reading with efficient parsing\n\n## Installation\n\n### Quick Install\n\n```bash\ncurl -o generate-docs-toc.sh https://raw.githubusercontent.com/danjdewhurst/docs-toc-generator/main/generate-docs-toc.sh\nchmod +x generate-docs-toc.sh\n```\n\n### Manual Install\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/danjdewhurst/docs-toc-generator.git\ncd docs-toc-generator\n```\n\n2. Make the script executable:\n```bash\nchmod +x generate-docs-toc.sh\n```\n\n3. (Optional) Add to your PATH:\n```bash\nsudo cp generate-docs-toc.sh /usr/local/bin/generate-docs-toc\n```\n\n## Usage\n\n### Basic Usage\n\nGenerate and print ToC to stdout (uses `docs/` directory by default):\n```bash\n./generate-docs-toc.sh\n```\n\n### Custom Directory\n\nScan a different documentation directory:\n```bash\n./generate-docs-toc.sh -d documentation\n```\n\n### Output to File\n\nWrite ToC to a specific file:\n```bash\n./generate-docs-toc.sh -o docs/README.md\n```\n\n### Simple Mode\n\nGenerate a minimal ToC without metadata:\n```bash\n./generate-docs-toc.sh --simple\n```\n\n### Filtering Files\n\nExclude specific files or patterns:\n```bash\n./generate-docs-toc.sh -e \"*.draft.md\" -e \"tmp/\" -e \"archive/\"\n```\n\nInclude only specific files:\n```bash\n./generate-docs-toc.sh -i \"*.md\"\n```\n\n### Sorting Options\n\nSort by modification date (newest first):\n```bash\n./generate-docs-toc.sh --sort date\n```\n\nSort by file size (largest first):\n```bash\n./generate-docs-toc.sh --sort size\n```\n\n### Grouping Options\n\nGroup by file type instead of directory:\n```bash\n./generate-docs-toc.sh --group-by type\n```\n\nNo grouping (flat list):\n```bash\n./generate-docs-toc.sh --group-by none\n```\n\n### Performance Optimization\n\nDisable snippet extraction for faster processing:\n```bash\n./generate-docs-toc.sh --no-snippets\n```\n\nLimit directory depth:\n```bash\n./generate-docs-toc.sh --max-depth 2\n```\n\n### Custom Snippet Length\n\nSet custom snippet length (default is 200 characters):\n```bash\n./generate-docs-toc.sh -l 300\n```\n\n### Custom Title\n\nSet a custom title for the ToC:\n```bash\n./generate-docs-toc.sh --title \"API Documentation Index\"\n```\n\n### Quiet Mode\n\nSuppress progress messages (useful in scripts):\n```bash\n./generate-docs-toc.sh -o TOC.md -q\n```\n\n### Combined Options\n\nHere are some useful combinations:\n\nGenerate a clean, fast ToC with filtering:\n```bash\n./generate-docs-toc.sh -d docs -o README.md --no-snippets -e \"*.draft.md\" -q\n```\n\nAPI documentation index sorted by date:\n```bash\n./generate-docs-toc.sh -d api --title \"API Reference\" --sort date --group-by type\n```\n\nOnly markdown files, limited depth, custom snippets:\n```bash\n./generate-docs-toc.sh -i \"*.md\" --max-depth 3 -l 150\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `-d, --directory DIR` | Documentation directory to scan (default: `docs`) |\n| `-o, --output FILE` | Write output to FILE instead of stdout |\n| `-s, --simple` | Simple mode (only paths and titles, no metadata) |\n| `-l, --snippet-length NUM` | Maximum snippet length in characters (default: 200) |\n| `--max-depth NUM` | Maximum directory depth to traverse (default: unlimited) |\n| `--sort [name\\|date\\|size]` | Sort files by name, date, or size (default: name) |\n| `-e, --exclude PATTERN` | Exclude files/dirs matching pattern (can be used multiple times) |\n| `-i, --include PATTERN` | Only include files matching pattern (can be used multiple times) |\n| `--no-snippets` | Disable snippet extraction for faster processing |\n| `--title TEXT` | Custom title for table of contents |\n| `--group-by [directory\\|type\\|none]` | How to group files (default: directory) |\n| `-q, --quiet` | Suppress progress messages |\n| `-h, --help` | Show help message |\n| `-v, --version` | Show version information |\n\n## Output Examples\n\n### Full Mode\n\n```markdown\n# Documentation Table of Contents\n\nGenerated: 2025-11-23\n\n**Total files:** 15 (12 markdown files)\n\n---\n\n## 📁 Plans\n\n- **[Project Roadmap](docs/plans/roadmap.md)**\n  This document outlines the strategic direction and planned features for the next quarter...\n  *3KB • Modified: 2025-11-15*\n\n- **[Architecture Design](docs/plans/architecture.md)**\n  Comprehensive system architecture covering microservices, data flow, and integration patterns...\n  *5KB • Modified: 2025-11-20*\n```\n\n### Simple Mode\n\n```markdown\n# Documentation Table of Contents\n\n- [Project Roadmap](docs/plans/roadmap.md)\n- [Architecture Design](docs/plans/architecture.md)\n- [API Reference](docs/api/reference.md)\n```\n\n## How It Works\n\nThe script processes your documentation directory (`docs/` by default) and:\n\n1. **Scans** all files in the documentation directory\n2. **Extracts** the first heading (h1 or h2) from each markdown file\n3. **Collects** a meaningful snippet of content (up to 200 characters)\n4. **Strips** markdown formatting for clean display\n5. **Gathers** file metadata (size and modification date)\n6. **Generates** a formatted table of contents in markdown\n\n### Smart Content Extraction\n\nThe script intelligently:\n- Skips empty lines and horizontal rules\n- Ignores metadata blocks and nested headings\n- Cleans markdown syntax (bold, italic, code, links)\n- Finds the most relevant content snippet\n\n## Requirements\n\n- Bash 3.2 or later (compatible with macOS default bash)\n- Standard Unix utilities: `find`, `sed`, `stat`, `awk`\n- Works on macOS and Linux\n\n## Use Cases\n\n- **Project Documentation**: Generate indexes for project wikis\n- **Knowledge Bases**: Create navigable ToCs for large documentation sets\n- **Static Sites**: Auto-generate documentation indexes\n- **CI/CD Integration**: Automatically update ToC on documentation changes\n- **Documentation Audits**: Quickly review all documentation with snippets\n\n## Integration Examples\n\n### Git Hook (Auto-update on commit)\n\nCreate `.git/hooks/pre-commit`:\n```bash\n#!/bin/bash\n./generate-docs-toc.sh -o docs/README.md\ngit add docs/README.md\n```\n\n### GitHub Actions\n\n**Auto-update ToC on documentation changes:**\n```yaml\nname: Update Documentation ToC\non:\n  push:\n    paths:\n      - 'docs/**'\njobs:\n  update-toc:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v2\n      - name: Generate ToC\n        run: |\n          chmod +x generate-docs-toc.sh\n          ./generate-docs-toc.sh -o docs/README.md\n      - name: Commit changes\n        run: |\n          git config --local user.email \"action@github.com\"\n          git config --local user.name \"GitHub Action\"\n          git add docs/README.md\n          git commit -m \"Auto-update documentation ToC\" || exit 0\n          git push\n```\n\n**Run tests on pull requests:**\n```yaml\nname: Test Suite\non: [push, pull_request]\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v2\n      - name: Install dependencies\n        run: |\n          sudo apt-get update\n          sudo apt-get install -y bats parallel\n      - name: Run tests\n        run: |\n          cd tests\n          ./run_tests.sh\n```\n\n### Makefile Integration\n\n```makefile\n.PHONY: docs-toc\ndocs-toc:\n\t./generate-docs-toc.sh -o docs/README.md\n\t@echo \"Documentation ToC updated!\"\n```\n\n## Performance\n\nThe script is optimized for performance:\n- Single-pass file reading (no multiple file reads)\n- Efficient regex matching with bash built-ins\n- Minimal external command calls\n- Handles hundreds of files quickly\n\n## Testing\n\nThis project includes a comprehensive test suite with **148 tests** covering all functionality.\n\n### Quick Test Run\n\n```bash\ncd tests\n./run_tests.sh\n```\n\n**Performance:** Tests run in parallel by default (~6 seconds on modern CPUs)\n\n### Test Coverage\n\n- ✅ **Core Functionality** (30 tests) - Script execution, output modes, metadata\n- ✅ **Command-line Arguments** (31 tests) - All flags and options\n- ✅ **Filtering \u0026 Sorting** (27 tests) - Include/exclude patterns, sort modes\n- ✅ **Grouping Options** (29 tests) - Directory, type, and flat grouping\n- ✅ **Markdown Processing** (31 tests) - Heading extraction, snippet generation\n\n### Prerequisites\n\n**Install Bats:**\n```bash\nbrew install bats-core  # macOS\n# or\nsudo apt-get install bats  # Linux\n```\n\n**Optional - Install GNU Parallel for 3x faster tests:**\n```bash\nbrew install parallel  # macOS\n# or\nsudo apt-get install parallel  # Linux\n```\n\n### Test Options\n\n```bash\n./run_tests.sh                  # Run all tests in parallel (~6 sec)\n./run_tests.sh --no-parallel    # Sequential execution (~18 sec)\n./run_tests.sh -j 4             # Use 4 parallel jobs\n./run_tests.sh --verbose        # Detailed output\n./run_tests.sh --filter \"heading\"  # Run specific tests\n```\n\n### Test Results\n\n```\nTotal Tests:  148 ✓\nSuccess Rate: 100%\nTime:         ~6 seconds (parallel) / ~18 seconds (sequential)\n```\n\nFor more details, see [tests/README.md](tests/README.md) or [tests/QUICK_START.md](tests/QUICK_START.md)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. **Run the test suite** to ensure everything works:\n   ```bash\n   cd tests\n   ./run_tests.sh\n   ```\n5. Add tests for new features\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\nAll pull requests must pass the test suite (148 tests) before merging.\n\n## Author\n\nCreated with ❤️ for better documentation management\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanjdewhurst%2Fdocs-toc-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanjdewhurst%2Fdocs-toc-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanjdewhurst%2Fdocs-toc-generator/lists"}