diff --git a/README.md b/README.md index 366de29..e8f7300 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ gh-md-toc is able to process: * local files (markdown files in local file system) * remote files (html files on github.com) -gh-md-toc tested on Ubuntu, and macOS High Sierra (gh-md-toc release 0.4.9). If you want it on Windows, you +gh-md-toc has been used on Ubuntu and macOS. CI currently runs the bats suite on Ubuntu (`ubuntu-latest`) under bash. If you want it on Windows, you better to use a golang based implementation: * [github-markdown-toc.go](https://github.com/ekalinin/github-markdown-toc.go) @@ -29,21 +29,21 @@ Table of contents ================= - * [Installation](#installation) - * [Usage](#usage) - * [STDIN](#stdin) - * [Local files](#local-files) - * [Remote files](#remote-files) - * [Multiple files](#multiple-files) - * [Combo](#combo) - * [Auto insert and update TOC](#auto-insert-and-update-toc) - * [GitHub token](#github-token) - * [TOC generation with Github Actions](#toc-generation-with-github-actions) - * [Tests](#tests) - * [Dependency](#dependency) - * [Docker](#docker) - * [Local](#local) - * [Public](#public) +* [Installation](#installation) +* [Usage](#usage) + * [STDIN](#stdin) + * [Local files](#local-files) + * [Remote files](#remote-files) + * [Multiple files](#multiple-files) + * [Combo](#combo) + * [Auto insert and update TOC](#auto-insert-and-update-toc) + * [GitHub token](#github-token) + * [TOC generation with Github Actions](#toc-generation-with-github-actions) +* [Tests](#tests) +* [Dependency](#dependency) +* [Docker](#docker) + * [Local](#local) + * [Public](#public) @@ -79,12 +79,14 @@ Here's an example of TOC creating for markdown from STDIN: ```bash ➥ cat ~/projects/Dockerfile.vim/README.md | ./gh-md-toc - - * [Dockerfile.vim](#dockerfilevim) - * [Screenshot](#screenshot) - * [Installation](#installation) - * [OR using Pathogen:](#or-using-pathogen) - * [OR using Vundle:](#or-using-vundle) - * [License](#license) +* [Dockerfile.vim](#dockerfilevim) +* [Screenshot](#screenshot) +* [Installation](#installation) + * [Or using Pathogen:](#or-using-pathogen) + * [Or using Vundle:](#or-using-vundle) + * [Or using NeoBundle:](#or-using-neobundle) + * [Or using Vim-Plug](#or-using-vim-plug) +* [License](#license) ``` Local files @@ -95,16 +97,19 @@ Here's an example of TOC creating for a local README.md: ```bash ➥ ./gh-md-toc ~/projects/Dockerfile.vim/README.md - Table of Contents ================= - * [Dockerfile.vim](#dockerfilevim) - * [Screenshot](#screenshot) - * [Installation](#installation) - * [OR using Pathogen:](#or-using-pathogen) - * [OR using Vundle:](#or-using-vundle) - * [License](#license) +* [Dockerfile.vim](#dockerfilevim) +* [Screenshot](#screenshot) +* [Installation](#installation) + * [Or using Pathogen:](#or-using-pathogen) + * [Or using Vundle:](#or-using-vundle) + * [Or using NeoBundle:](#or-using-neobundle) + * [Or using Vim-Plug](#or-using-vim-plug) +* [License](#license) + + ``` To include only headings up to a given level, use `--depth `: @@ -140,40 +145,45 @@ There is nothing easier: Table of Contents ================= - * [envirius](#envirius) - * [Idea](#idea) - * [Features](#features) - * [Installation](#installation) - * [Uninstallation](#uninstallation) - * [Available plugins](#available-plugins) - * [Usage](#usage) - * [Check available plugins](#check-available-plugins) - * [Check available versions for each plugin](#check-available-versions-for-each-plugin) - * [Create an environment](#create-an-environment) - * [Activate/deactivate environment](#activatedeactivate-environment) +* [envirius](#envirius) + * [Table of Contents](#table-of-contents) + * [Idea](#idea) + * [Features](#features) +* [Installation](#installation) +* [Uninstallation](#uninstallation) +* [Available plugins](#available-plugins) +* [Usage](#usage) + * [Check available plugins](#check-available-plugins) + * [Check available versions for each plugin](#check-available-versions-for-each-plugin) + * [Create an environment](#create-an-environment) + * [Activate/deactivate environment](#activatedeactivate-environment) * [Activating in a new shell](#activating-in-a-new-shell) * [Activating in the same shell](#activating-in-the-same-shell) - * [Get list of environments](#get-list-of-environments) - * [Get current activated environment](#get-current-activated-environment) - * [Do something in environment without enabling it](#do-something-in-environment-without-enabling-it) - * [Get help](#get-help) - * [Get help for a command](#get-help-for-a-command) - * [How to add a plugin?](#how-to-add-a-plugin) - * [Mandatory elements](#mandatory-elements) + * [Get list of environments](#get-list-of-environments) + * [Get current activated environment](#get-current-activated-environment) + * [Do something in environment without enabling it](#do-something-in-environment-without-enabling-it) + * [Export environment into tar archive](#export-environment-into-tar-archive) + * [Import environment from tar archive](#import-environment-from-tar-archive) + * [Get help](#get-help) + * [Get help for a command](#get-help-for-a-command) +* [How to add a plugin?](#how-to-add-a-plugin) + * [Mandatory elements](#mandatory-elements) * [plug_list_versions](#plug_list_versions) * [plug_url_for_download](#plug_url_for_download) * [plug_build](#plug_build) - * [Optional elements](#optional-elements) + * [Optional elements](#optional-elements) * [Variables](#variables) * [Functions](#functions) - * [Examples](#examples) - * [Example of the usage](#example-of-the-usage) - * [Dependencies](#dependencies) - * [Supported OS](#supported-os) - * [Tests](#tests) - * [Version History](#version-history) - * [License](#license) - * [README in another language](#readme-in-another-language) + * [Examples](#examples) +* [Example of the usage](#example-of-the-usage) +* [Dependencies](#dependencies) +* [Supported OS](#supported-os) +* [Tests](#tests) +* [Version History](#version-history) +* [License](#license) +* [README in another language](#readme-in-another-language) + + ``` That's all! Now all you need — is copy/paste result from console into original @@ -193,9 +203,16 @@ Moreover, it's able to work with GitHub's wiki pages: Table of Contents ================= - * [Who Uses Nodeenv?](#who-uses-nodeenv) - * [OpenStack](#openstack) - * [pre-commit.com](#pre-commitcom) +* [Who Uses Nodeenv?](#who-uses-nodeenv) + * [edx](#edx) + * [OpenStack](#openstack) + * [HSReplay.net](#hsreplaynet) + * [pre-commit.com](#pre-commitcom) + * [sailing-channels.com](#sailing-channelscom) + * [Galaxy](#galaxy) + * [Lambdas in Python with Serverless.com](#lambdas-in-python-with-serverlesscom) + + ``` Multiple files @@ -205,23 +222,32 @@ It supports multiple files as well: ```bash ➥ ./gh-md-toc \ - https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md \ - https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md \ - https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md \ - https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md - - * [Hello world](https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md#hello-world) + https://github.com/bandali/rust-for-c/blob/master/hello_world/README.md \ + https://github.com/bandali/rust-for-c/blob/master/control_flow/README.md \ + https://github.com/bandali/rust-for-c/blob/master/data_types/README.md \ + https://github.com/bandali/rust-for-c/blob/master/unique/README.md + +* [Introduction - hello world!](https://github.com/bandali/rust-for-c/blob/master/hello_world/README.md#introduction---hello-world) + * [1](https://github.com/bandali/rust-for-c/blob/master/hello_world/README.md#1) + +* [Control flow](https://github.com/bandali/rust-for-c/blob/master/control_flow/README.md#control-flow) + * [If](https://github.com/bandali/rust-for-c/blob/master/control_flow/README.md#if) + * [Loops](https://github.com/bandali/rust-for-c/blob/master/control_flow/README.md#loops) + * [For loops](https://github.com/bandali/rust-for-c/blob/master/control_flow/README.md#for-loops) + * [Switch/Match](https://github.com/bandali/rust-for-c/blob/master/control_flow/README.md#switchmatch) + * [Method call](https://github.com/bandali/rust-for-c/blob/master/control_flow/README.md#method-call) + +* [Data types](https://github.com/bandali/rust-for-c/blob/master/data_types/README.md#data-types) + * [Structs](https://github.com/bandali/rust-for-c/blob/master/data_types/README.md#structs) + * [Tuples](https://github.com/bandali/rust-for-c/blob/master/data_types/README.md#tuples) + * [Tuple structs](https://github.com/bandali/rust-for-c/blob/master/data_types/README.md#tuple-structs) + * [Enums](https://github.com/bandali/rust-for-c/blob/master/data_types/README.md#enums) + * [Option](https://github.com/bandali/rust-for-c/blob/master/data_types/README.md#option) + * [Inherited mutabilty and Cell/RefCell](https://github.com/bandali/rust-for-c/blob/master/data_types/README.md#inherited-mutabilty-and-cellrefcell) + +* [Unique pointers](https://github.com/bandali/rust-for-c/blob/master/unique/README.md#unique-pointers) - * [Control Flow](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#control-flow) - * [If](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#if) - * [Loops](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#loops) - * [For loops](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#for-loops) - * [Switch/Match](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#switchmatch) - * [Method call](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#method-call) - - * [Primitive Types and Operators](https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md#primitive-types-and-operators) - - * [Unique Pointers](https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md#unique-pointers) + ``` Combo @@ -231,24 +257,37 @@ You can easily combine both ways: ```bash ➥ ./gh-md-toc \ - ~/projects/Dockerfile.vim/README.md \ - https://github.com/ekalinin/sitemap.s/blob/master/README.md - - * [Dockerfile.vim](~/projects/Dockerfile.vim/README.md#dockerfilevim) - * [Screenshot](~/projects/Dockerfile.vim/README.md#screenshot) - * [Installation](~/projects/Dockerfile.vim/README.md#installation) - * [OR using Pathogen:](~/projects/Dockerfile.vim/README.md#or-using-pathogen) - * [OR using Vundle:](~/projects/Dockerfile.vim/README.md#or-using-vundle) - * [License](~/projects/Dockerfile.vim/README.md#license) - - * [sitemap.js](https://github.com/ekalinin/sitemap.js/blob/master/README.md#sitemapjs) - * [Installation](https://github.com/ekalinin/sitemap.js/blob/master/README.md#installation) - * [Usage](https://github.com/ekalinin/sitemap.js/blob/master/README.md#usage) - * [License](https://github.com/ekalinin/sitemap.js/blob/master/README.md#license) + /home/you/projects/Dockerfile.vim/README.md \ + https://github.com/ekalinin/sitemap.js/blob/master/README.md + +* [Dockerfile.vim](/home/you/projects/Dockerfile.vim/README.md#dockerfilevim) +* [Screenshot](/home/you/projects/Dockerfile.vim/README.md#screenshot) +* [Installation](/home/you/projects/Dockerfile.vim/README.md#installation) + * [Or using Pathogen:](/home/you/projects/Dockerfile.vim/README.md#or-using-pathogen) + * [Or using Vundle:](/home/you/projects/Dockerfile.vim/README.md#or-using-vundle) + * [Or using NeoBundle:](/home/you/projects/Dockerfile.vim/README.md#or-using-neobundle) + * [Or using Vim-Plug](/home/you/projects/Dockerfile.vim/README.md#or-using-vim-plug) +* [License](/home/you/projects/Dockerfile.vim/README.md#license) + +* [sitemap MIT LicenseBuild StatusMonthly Downloads](https://github.com/ekalinin/sitemap.js/blob/master/README.mdhttps://camo.githubusercontent.com/58b74923f31b284091105e7ef6a0a576b1d28fd205d401521cd4eab677a93f39/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f736974656d6170) + * [Table of Contents](https://github.com/ekalinin/sitemap.js/blob/master/README.md#table-of-contents) + * [Installation](https://github.com/ekalinin/sitemap.js/blob/master/README.md#installation) + * [Generate a one time sitemap from a list of urls](https://github.com/ekalinin/sitemap.js/blob/master/README.md#generate-a-one-time-sitemap-from-a-list-of-urls) + * [Serve a sitemap from a server and periodically update it](https://github.com/ekalinin/sitemap.js/blob/master/README.md#serve-a-sitemap-from-a-server-and-periodically-update-it) + * [Create sitemap and index files from one large list](https://github.com/ekalinin/sitemap.js/blob/master/README.md#create-sitemap-and-index-files-from-one-large-list) + * [Options you can pass](https://github.com/ekalinin/sitemap.js/blob/master/README.md#options-you-can-pass) + * [Filtering sitemap entries during parsing](https://github.com/ekalinin/sitemap.js/blob/master/README.md#filtering-sitemap-entries-during-parsing) + * [Examples](https://github.com/ekalinin/sitemap.js/blob/master/README.md#examples) + * [API](https://github.com/ekalinin/sitemap.js/blob/master/README.md#api) + * [Maintainers](https://github.com/ekalinin/sitemap.js/blob/master/README.md#maintainers) + * [License](https://github.com/ekalinin/sitemap.js/blob/master/README.md#license) ``` +Note: the shell expands `~/projects/...` to an absolute path, so the generated links use that absolute path, not `~`. + + Auto insert and update TOC -------------------------- @@ -267,20 +306,19 @@ $ ./gh-md-toc --insert README.test.md Table of Contents ================= - * [gh-md-toc](#gh-md-toc) - * [Installation](#installation) - * [Usage](#usage) - * [STDIN](#stdin) - * [Local files](#local-files) - * [Remote files](#remote-files) - * [Multiple files](#multiple-files) - * [Combo](#combo) - * [Tests](#tests) - * [Dependency](#dependency) +* [Dockerfile.vim](#dockerfilevim) +* [Screenshot](#screenshot) +* [Installation](#installation) + * [Or using Pathogen:](#or-using-pathogen) + * [Or using Vundle:](#or-using-vundle) + * [Or using NeoBundle:](#or-using-neobundle) + * [Or using Vim-Plug](#or-using-vim-plug) +* [License](#license) +Found markers !! TOC was added into: 'README.test.md' -!! Origin version of the file: 'README.test.md.orig.2018-02-04_192655' -!! TOC added into a separate file: 'README.test.md.toc.2018-02-04_192655' +!! Origin version of the file: 'README.test.md.orig.2026-10-02_120000' +!! TOC added into a separate file: 'README.test.md.toc.2026-10-02_120000' @@ -289,22 +327,19 @@ Table of Contents Now check the same file: ```bash -➜ grep -A15 "<\!\-\-ts" README.test.md +➜ grep -A20 "<\!--ts" README.test.md - * [gh-md-toc](#gh-md-toc) - * [Table of contents](#table-of-contents) - * [Installation](#installation) - * [Usage](#usage) - * [STDIN](#stdin) - * [Local files](#local-files) - * [Remote files](#remote-files) - * [Multiple files](#multiple-files) - * [Combo](#combo) - * [Auto insert and update TOC](#auto-insert-and-update-toc) - * [Tests](#tests) - * [Dependency](#dependency) - - +* [Dockerfile.vim](#dockerfilevim) +* [Screenshot](#screenshot) +* [Installation](#installation) + * [Or using Pathogen:](#or-using-pathogen) + * [Or using Vundle:](#or-using-vundle) + * [Or using NeoBundle:](#or-using-neobundle) + * [Or using Vim-Plug](#or-using-vim-plug) +* [License](#license) + + + ``` @@ -369,18 +404,21 @@ on: branches: [main] paths: ['foo.md'] +permissions: + contents: write + jobs: build: runs-on: ubuntu-latest timeout-minutes: 5 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v7 - run: | curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc chmod a+x gh-md-toc ./gh-md-toc --insert --no-backup --hide-footer foo.md rm gh-md-toc - - uses: stefanzweifel/git-auto-commit-action@v4 + - uses: stefanzweifel/git-auto-commit-action@v7 with: commit_message: Auto update markdown TOC ``` @@ -398,18 +436,11 @@ Useful articles: How to run tests: ```bash -➥ make test - - ✓ TOC for local README.md - ✓ TOC for remote README.md - ✓ TOC for mixed README.md (remote/local) - ✓ TOC for markdown from stdin - ✓ --help - ✓ --version - -6 tests, 0 failures +➥ make test ``` +That runs the bats suite (currently 17 tests on `master`). Prefer `make test` over copying a hand-maintained checklist — new cases land often. + Dependency ========== @@ -419,7 +450,7 @@ Dependency * sed * bats (for unit tests) -Tested on Ubuntu 14.04/14.10 in bash/zsh. +CI runs the bats suite on Ubuntu (`ubuntu-latest`) under bash. Docker ====== @@ -449,11 +480,13 @@ Public ------- ```shell -$ docker pull evkalinin/gh-md-toc:0.7.0 +$ docker pull evkalinin/gh-md-toc:0.10.0 $ docker images | grep toc -evkalinin/gh-md-toc 0.7.0 0b8db6aed298 11 minutes ago 147MB +evkalinin/gh-md-toc 0.10.0 2024-03-03 ~72MB -$ docker run -it evkalinin/gh-md-toc:0.7.0 \ +$ docker run -it evkalinin/gh-md-toc:0.10.0 \ https://github.com/ekalinin/envirius/blob/master/README.md ``` + +The published `0.10.0` image was built in March 2024 from that tag. It does not include later `master` fixes (for example remote first-heading handling from #170) and does not support `--depth`. For current behaviour, build from this repository (`docker build -t markdown-toc-generator .`) or run `./gh-md-toc` locally.