diff --git a/.babelrc b/.babelrc deleted file mode 100644 index ef749a2..0000000 --- a/.babelrc +++ /dev/null @@ -1,16 +0,0 @@ -{ - "env": { - "development": { - "presets": ["env"], - "plugins": [ - "add-module-exports" - ] - }, - "production": { - "presets": ["env", "minify"], - "plugins": [ - "add-module-exports" - ] - } - } -} diff --git a/.eslintignore b/.eslintignore deleted file mode 100644 index d636432..0000000 --- a/.eslintignore +++ /dev/null @@ -1,2 +0,0 @@ -coverage -lib diff --git a/.eslintrc b/.eslintrc deleted file mode 100644 index 66cc62d..0000000 --- a/.eslintrc +++ /dev/null @@ -1,13 +0,0 @@ -{ - "parser": "babel-eslint", - "extends": "airbnb", - "env": { - "mocha": true - }, - "rules": { - "comma-dangle": ["error", "only-multiline"], - "consistent-return": "off", - "prefer-template": "off", - "prefer-destructuring": "off" - } -} diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6313b56 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..5f0618d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,29 @@ +name: CI + +on: + push: + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] + node: ['22.13.0', '22.x', '24.x', '26.x'] + include: + - os: windows-latest + node: '24.x' + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: ${{ matrix.node }} + cache: npm + - run: npm ci + - run: npm run lint + - run: npm test diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..ebb5ce1 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,23 @@ +name: Release + +on: + release: + types: [published] + +permissions: + contents: read + id-token: write + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 24.x + package-manager-cache: false + registry-url: https://registry.npmjs.org + - run: npm ci + - run: npm test + - run: npm publish diff --git a/.gitignore b/.gitignore index f879349..14454f9 100644 --- a/.gitignore +++ b/.gitignore @@ -33,11 +33,7 @@ jspm_packages # Editors .idea -# Lib -lib - # npm package lock -package-lock.json yarn.lock # others diff --git a/.npmignore b/.npmignore deleted file mode 100644 index c638fdb..0000000 --- a/.npmignore +++ /dev/null @@ -1,28 +0,0 @@ -*.log -npm-debug.log* - -# Coverage directory used by tools like istanbul -coverage -.nyc_output - -# Dependency directories -node_modules - -# npm package lock -package-lock.json -yarn.lock - -.vscode - -# project files -src -test -docs -CHANGELOG.md -.travis.yml -.editorconfig -.eslintignore -.eslintrc -.babelrc -.gitignore -.nvmrc diff --git a/.nvmrc b/.nvmrc index d3a8b24..2bd5a0a 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -v8.11.1 +22 diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 2da3f8d..0000000 --- a/.travis.yml +++ /dev/null @@ -1,10 +0,0 @@ -language: node_js -node_js: - - '10' - - '8' -script: - - npm run test - - npm run build -branches: - only: - - master diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3e3e65a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,26 @@ +# Changelog + +## 3.0.0 + +### Breaking + +- Node `>=22.13.0`. +- `llms.txt` and `llms-full.txt` are written by default. `--no-llm` turns them off. +- A base URL is required unless tocsify can detect one. +- Anchors in `toc.md` now use Docsify 5 ids. This changes links for headings with leading digits, accents, emoji, `:id=`, links, or `#`. +- `-h` now means `--help` instead of `--header`. +- `bin` and `main` move to `src/cli.js`. `lib/` is gone. `exports` blocks deep imports. +- `dir` defaults to `docs`. + +### Fixes + +- The underscore skip rule. +- Exact `README.md` and `index.md` matching. +- Comment-form ignore markers. +- Help text that said `--maxdepth` defaults to 3. +- The demo loading Docsify 4.13.1. +- Tests that asserted nothing. + +### Removed + +- Every runtime dependency. This clears the markdown-toc and meow audit findings. diff --git a/README.md b/README.md index 4169578..4325938 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,126 @@ -# 📋 tocsify +# tocsify [![NPM version](https://img.shields.io/npm/v/tocsify.svg?style=flat)](https://www.npmjs.com/package/tocsify) [![NPM downloads](https://img.shields.io/npm/dm/tocsify.svg?style=flat)](https://npmjs.org/package/tocsify) -📋 npm module that **generates a table of contents** based on the **file structure** of a [Docsify](https://docsify.js.org) `docs` directory! +tocsify reads a Docsify 5 `docs` folder and writes three files: -## Features +- `docs/toc.md`, a table of contents +- `docs/llms.txt`, an index for LLMs +- `docs/llms-full.txt`, the full text of every page -* Adds relative path to title in each top-level entry for context. -* Skips markdown files beginning with `_`. -* Allows users to specify `maxdepth` for cleaner generation. -* Skips generation for headers marked `{docsify-ignore}` -* If `{docsify-ignore-all}` exists in a top level header (`# Example Header {docsify-ignore-all}`), skip generating the table of contents for the entire document. - -## Installation - -Install globally for use in any [Docsify](https://docsify.js.org) project! +## Install ```bash npm install -g tocsify ``` +Node.js `>=22.13.0` is required. + ## Usage -```bash - Usage - $ tocsify docs --file=docs/toc.md - - Options - --verbose, -v Write output to stdout. - --file, -f Write output to file. - --header, -h Include a descriptive header. Default is true. - --maxdepth, -m Specify max level header(1 - 6) to output. Default is 3. - - Examples - $ tocsify docs --file=docs/toc.md - $ tocsify docs --verbose --file=docs/toc.md - $ tocsify docs --maxdepth=2 - $ tocsify docs --header=false +```text +Usage + $ tocsify [dir] [options] + + dir defaults to docs. + +Options + --file, -f Path of the table of contents. Default: docs/toc.md + --maxdepth, -m Deepest heading level, 1 to 6. Default: 6 + --no-header Do not prefix page links with ###. + --verbose, -v Also print the table of contents to stdout. + --no-llm Do not write llms.txt and llms-full.txt. + --base-url Site URL for links in the llms files. Detected if not set. + --title Title for llms.txt. Default: H1 of the home page + --summary Summary for llms.txt. Default: first paragraph of the home page + --group h2 or sidebar. Default: h2 + --keep-comments Keep HTML comments in llms-full.txt. + --help, -h Show this help. + --version Show the version. + +Examples + $ tocsify docs + $ tocsify docs --maxdepth=2 --no-header + $ tocsify docs --base-url=https://example.com/docs/ + $ tocsify docs --no-llm +``` + +`-h` means `--help`. It used to mean `--header`. + +## Base URL + +`llms.txt` and `llms-full.txt` use absolute links. tocsify picks the first hit: + +1. `--base-url`, which must start with `http://` or `https://` +2. The first non-empty line of `/CNAME` +3. `GITHUB_REPOSITORY`, as `https://owner.github.io/repo/` +4. `git remote origin`, when it is a GitHub URL +5. `homepage` in `package.json` + +Pass `--base-url` when the docs folder is not the GitHub Pages root. `--no-llm` skips this step and writes only `toc.md`. + +In `llms-full.txt`, each relative link becomes the URL Docsify 5 loads with its default `relativePath: false`. Markdown links, ``, and `` resolve from the docs root. Markdown images resolve from the page folder. A link that starts with `/` resolves from the base URL, which is the docs root. + +## GitHub Actions + +Run tocsify on push to `main`, then commit the three files when they change. A push made with `GITHUB_TOKEN` does not start another workflow run. + +```yaml +name: Docs +on: + push: + branches: [main] +permissions: + contents: write +jobs: + llms: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 24.x + - run: npx tocsify@3 docs + - run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add docs/toc.md docs/llms.txt docs/llms-full.txt + git diff --cached --quiet || git commit -m "docs: update toc and llms files" + git push +``` + +## Docsify 5 + +Put these two links in ``: + +```html + + ``` -## Integration +Put a `