diff --git a/README.md b/README.md index fa08be2..5e0bb05 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # repo-toc [![npm version](https://badge.fury.io/js/repo-toc.svg)](https://badge.fury.io/js/repo-toc) -Easily generate a markdown Table of Contents (TOC) for your GitHub repository. +Easily generate a markdown Table of Contents (TOC) for your GitHub repository. Automatically respects `.gitignore` files and excludes ignored files and directories from the TOC. ## Installation @@ -55,13 +55,27 @@ Options: -x, --exclude Directories to exclude (comma-separated) [string] -h, --help Show help [boolean] -Note: Files and directories in .gitignore are automatically excluded. +**Important**: Files and directories listed in `.gitignore` files are automatically excluded from the TOC generation. This includes: +- Files and directories specified in `.gitignore` at any level in your repository +- Common ignored patterns like `node_modules/`, `dist/`, `build/`, `.git/`, etc. +- You can still use the `--exclude` option to exclude additional directories beyond what's in `.gitignore` ``` ``` repo-toc ``` +### .gitignore Support + +`repo-toc` automatically respects `.gitignore` files throughout your repository: + +- **Automatic exclusion**: Files and directories listed in `.gitignore` are automatically excluded from TOC generation +- **Multi-level support**: Respects `.gitignore` files at any directory level in your repository +- **Common patterns**: Automatically excludes common ignored patterns like `node_modules/`, `dist/`, `build/`, `.git/`, etc. +- **Additional exclusions**: You can still use the `--exclude` option to exclude additional directories beyond what's in `.gitignore` + +This ensures your TOC only includes files that are actually tracked in your repository, keeping it clean and relevant. + ### Usage Examples Generate TOC excluding specific directories: @@ -74,7 +88,123 @@ Generate TOC for only JavaScript files, excluding test directories: repo-toc --ext .js,.ts --exclude tests,__tests__,spec ``` -**Note**: The tool automatically respects `.gitignore` files and excludes any files or directories listed there, in addition to your manual exclusions. +**Note**: The tool automatically respects `.gitignore` files and excludes any files or directories listed there, in addition to your manual exclusions. This ensures your TOC only includes files that are actually tracked in your repository. + +### Use with Pre-commit Hooks + +You can integrate `repo-toc` with pre-commit hooks to automatically generate and update the TOC before each commit. This ensures your TOC is always up-to-date. + +#### Setup + +1. **Install pre-commit** (if not already installed): +```bash +pip install pre-commit +``` + +2. **Add repo-toc to your package.json**: +```json +{ + "devDependencies": { + "repo-toc": "^1.2.0" + }, + "scripts": { + "generate-toc": "./.github/hooks/generate-toc.sh", + "install-hooks": "pre-commit install" + } +} +``` + +3. **Create a pre-commit hook script** (`.github/hooks/generate-toc.sh`): +```bash +#!/bin/bash +set -e + +echo "🔄 Generating Table of Contents..." + +# Check if Node.js and npm are available +if ! command -v node &> /dev/null || ! command -v npm &> /dev/null; then + echo "❌ Node.js/npm is not installed. Please install Node.js to generate TOC." + exit 1 +fi + +# Install repo-toc if not already installed +if ! npm list -g repo-toc &> /dev/null; then + echo "đŸ“Ļ Installing repo-toc globally..." + npm install -g repo-toc +fi + +# Generate TOC for README.md +if [ -f "README.md" ]; then + echo "📝 Updating Table of Contents in README.md..." + + # Create a backup + cp README.md README.md.backup + + # Generate TOC with repo-toc + repo-toc -i README.md + + # Check if the file was modified + if ! cmp -s README.md README.md.backup; then + echo "✅ Table of Contents updated successfully!" + # Add the updated file to git staging area + git add README.md + else + echo "ℹī¸ Table of Contents is already up to date." + fi + + # Clean up backup + rm README.md.backup +else + echo "❌ README.md not found in current directory" + exit 1 +fi + +echo "🎉 TOC generation completed!" +``` + +4. **Configure pre-commit** (`.pre-commit-config.yaml`): +```yaml +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-markdown + args: [--fix] + + - repo: local + hooks: + - id: generate-toc + name: Generate Table of Contents + entry: ./.github/hooks/generate-toc.sh + language: script + files: '^README\.md$' + pass_filenames: false + stages: [commit] + + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.37.0 + hooks: + - id: markdownlint + args: [--fix] + files: \.md$ +``` + +5. **Install the pre-commit hooks**: +```bash +npm run install-hooks +# or +pre-commit install +``` + +#### Benefits + +- **Automatic TOC updates**: TOC is generated/updated automatically before each commit +- **Consistent formatting**: Ensures TOC follows the same format across all commits +- **No manual intervention**: Developers don't need to remember to update the TOC +- **Integration with other hooks**: Works seamlessly with markdown linting and other pre-commit hooks ### Use with Github actions It will auto generate the TOC after you commit things on Github. You use this github action @@ -155,7 +285,9 @@ Generates a Table of Contents for the specified directory. - **`filePath`** (string): The path where the generated TOC will be written. - Default: `__dirname + "/README.md"`. - **`excludedDirs`** (array of strings): An array of directory names to exclude from the TOC. - - Default: `[]`. Note: Directories starting with `.` and files/directories in `.gitignore` are automatically excluded. + - Default: `[]`. + - **Automatic exclusions**: Directories starting with `.` and files/directories listed in `.gitignore` files are automatically excluded, regardless of this parameter. + - This parameter allows you to exclude additional directories beyond what's already ignored by `.gitignore`. **Returns**: `void`