ekalinin / github-markdown-toc Goto Github PK
View Code? Open in Web Editor NEWEasy TOC creation for GitHub README.md
License: MIT License
Easy TOC creation for GitHub README.md
License: MIT License
I cant create for my nonstandard.js
package
https://github.com/LestaD/nonstandard.js
I'm not getting the expected results:
Here's what I've done:
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 /Users/seamus/Documents/GitHub/PiFormulae/CreatingRationalMusicLibrary2.md > new-with-toc.txt
cat new-with-toc.txt
* [Create a Rational and Portable File Server for Your Music Library](#create-a-rational-and-portable-file-server-for-your-music-library)
* [0. Objective](#0-objective)
* [1. Select the USB storage media](#1-select-the-usb-storage-media)
* [2. Create and format a partition](#2-create-and-format-a-partition)
* [2. Mounting a network storage device:](#2-mounting-a-network-storage-device)
* [3. Copy/Sync Music repositories](#3-copysync-music-repositories)
* [3.ALT Copy Music repositories using install](#3alt-copy-music-repositories-using-install)
* [4. Serve!](#4-serve)
* [Linux vs. Samba <em><strong>permissions</strong></em>](#linux-vs-samba-permissions)
* [Samba profile for single user pi](#samba-profile-for-single-user-pi)
* [Samba profile for read-only guest access, write access for user pi](#samba-profile-for-read-only-guest-access-write-access-for-user-pi)
Created by gh-md-toc
After a select+C&P into my .md file & uploading, this doesn't render properly on my github page:
(https://github.com/seamusdemora/PiFormulae/blob/master/CreatingRationalMusicLibrary2.md)
Under OS X no TOC is returned. I tried the current master
as well as version 0.4.4
as recommended in issue #15.
This is the output of version 0.4.4
:
$ gh-md-toc README.md
Table of Contents
=================
grep: unrecognized option `--null-data'
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
[-e pattern] [-f file] [--binary-files=value] [--color=when]
[--context[=num]] [--directories=action] [--label] [--line-buffered]
[--null] [pattern] [file ...]
(23) Failed writing body
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
The current master has no output at all.
Hello,
Thanks for such a convenient tool! Works great for me on multiple linux platforms.
Unfortunately in OS X the current version returns no TOC lines, even with input .md files that produce the expected output in linux. Looks like it may be related to argument to $GH_GREP
in gh_toc_grab()
.Any ideas?
$ grep --version
grep (BSD grep) 2.5.1-FreeBSD
$ uname -a
Darwin macbookone.local 14.4.0 Darwin Kernel Version 14.4.0: Thu May 28 11:35:04 PDT 2015; root:xnu-2782.30.5~1/RELEASE_X86_64 x86_64
$ ./gh-md-toc ~/src.mywork.gitRepos/stowlerGeneralComputing/docs/setupBasicScriptingEnvironment.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
$
Howdy, This isn't an issue, but I created a docker image that runs your script internally.
https://hub.docker.com/r/hipposareevil/github-markdown-toc/
I have it working for the cat version of your usage:
cat README.md | docker run -i hipposareevil/github-markdown-toc
Consider supporting ordered lists instead of assuming unordered lists. Wikipedia uses this TOC style.
Hi, love this tool.
Is it possible to add an option to generate a list of items starting with a dash rather than an asterisk?
The false space character is c2 in hexadecimal (194 in decimal).
In a title, it causes gh-md-toc to skip the title.
Example
## real space
## bad-space
The bad space is after the 2 sharp characters.
I don't know how I got that false space in the first place !
Hi. I just wanted to let You know that while this works perfectly for English-only characters, some letters with accents and other diacritical signs get "messed up" in the process.
For example, ň
goes to %C5%88
, and í
goes to %C3%AD
.
I guess the links still work, but it's ugly, and modern browsers can handle these special accentuated letters without a problem.
I suspect this has to do with character encoding, but I am not sure whether this is intentional, or, if not, how to fix this. Thus this issue.
Thank You for Your time and effort
I've been working on some dynamic blocks for Gutenberg (dynamic in that they output html in the render_callback of block registration). Any headings I insert into the content in this way are not picked up by Easy TOC. Not inserted into the TOC at all.
I'm using the shortcode, not automatic TOC insertion.
I think this is because the shortcode runs before the blocks are rendered and builds the TOC against the stored post content, not the actual final output.
Is there anything i can do to easily change easy TOC so that the shortcode just adds filters to insert the TOC that run on the final content?
I'd like to have global TOC for number of files (say, chapter-1.md, chapter-2.md, etc) and place it in README or index.md (as we use gh-pages, we want index). Is it possible with your tool? Would it be possible to add this feature to your tool?
I was using the direct insert flag --insert
to directly insert the TOC into the readme.md
. I've added the two lines
<!--ts-->
<!--te-->
into the readme but when running the script with the --insert
flag I get the output:
You don't have <!--ts--> or <!--te--> in your file...exiting
I've found the part in the script that does the search for the tags
if grep -Fxq "<!--ts-->" $gh_src && grep -Fxq "<!--te-->" $gh_src; then
which seems to fail. I've run the command manually on Linux Mint 19
grep -Fxq "<!--ts-->" Readme.md
and I get the error
bash: !-: event not found
For my workaround I had to escape the syntax to this form
if grep -xq "<\!--ts-->" $gh_src && grep -xq "<\!--te-->" $gh_src; then
Line 178 returns the following error
./gh-md-toc: line 178: [: =: unary operator expected```
should probably be changed to
if [ "$no_backup" = "yes" ]; then
To automatize the TOC generation,
it would be nice that gh-md-toc generates the TOC inside the MD file, instead of generating some text that user has to manually insert at the desired position.
So, if the markdown file has a marker like:
<!-- TOC -->
gh-md-toc generates or re-generates the TOC at this position.
To re-generate the TOC, and delete the old TOC, the end of TOC could be marked by something like:
<!-- gh-md-toc end , generated at samedi 25 novembre 2017, 04:08:42 (UTC+0100) by jmv -->
Hi
Thanks for making this solution!
I tried both for local and remote, all like below. is there some package I need to install?
I have all the dependency except bats
./gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv
Created by gh-md-toc
Hi,
Your tool looks great and would save a lot of work for me.
However when I tried your tool with one of my wiki page
gh-md-toc https://github.com/box/TestScribe/wiki/FAQ
I got the following error
Table of Contents
=================
grep: unrecognized option `--null-data'
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
[-e pattern] [-f file] [--binary-files=value] [--color=when]
[--context[=num]] [--directories=action] [--label] [--line-buffered]
[--null] [pattern] [file ...]
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
I got the same error when I run it with a local .md file.
What did I miss?
$ gh-md-toc https://github.com/pavelsr/awesome-services/blob/master/README.md
Table of Contents
=================
* [Предисловие]()
* [Сервисы, которые не требуют специальных навыков.]()
* [Яндекс.Толока]()
* [Workle]()
* [YouDO]()
* [Divly]()
* [Для кодеров от сотоны]()
* [Hack.Hands]()
* [Bountysource]()
* [Криптовалюта]()
* [ICO]()
* [Для журналистов, блоггеров и всех кто может и любит делиться оригинальным контентом]()
* [Golos.io]()
* [Тинькофф.Журнал]()
* [Свой YouTube канал]()
* [Для маркетологов от бога]()
* [Арбитраж трафика]()
* [Для мейкеров]()
* [Для предпринимателей]()
* [Для дизайнеров]()
* [Для водителей]()
* [Грузоперевозки]()
* [Совместные междугородние поездки]()
* [Для всех, у кого есть жильё]()
* [Для путешественников]()
* [Биржи удалённых работ]()
* [Сервисы для оптимальных покупок (экономия)]()
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
$ gh-md-toc --version
0.5.0
Love the idea but all of our README's use the # H1
, ## H2
, etc style. Would be awesome to support that!
Given:
## Foo
### Bar
The following is output:
Table of Contents
=================
* [Foo](#foo)
* [Bar](#bar)
Given the leading space, the TOC is code formatted. This is because my document has no H1.
In this case the documents are on GitHub's wiki, so the H1 is supplied by them.
This is a great script when it works.
But some md file I have doesn't work.
eg,
./gh-md-toc https://github.com/rickyzhang82/concurrent-programming/raw/master/doc/NOTE.md
I saw another issue. Some guy reached conclusion that it is related to GNU awk version. Any suggestions to work around it? eg, use docker?
Hi,
First, thanks for this useful script. Second, it seems to me that there is a problem when a title has a backquote at the end. Here is an example with this simple markdown file:
# The command `foo1`
Blabla...
# The command `foo2` is better
Blabla...
# The command `bar1`
Blabla...
# The command `bar2` is better
Blabla...
I have this:
~$ ./gh-md-toc /tmp/test.md
Table of Contents
=================
* [](#the-command-foo1)
* [The command <code>foo2</code> is better](#the-command-foo2-is-better)
* [](#the-command-bar1)
* [The command <code>bar2</code> is better](#the-command-bar2-is-better)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
Regards
Thanks for this tool, I tried it out today. Maybe you want to tweak your build process for the binaries...
After unpacking the tgz then the tar file, I noticed that the windows binaries don't have a '.exe' on the end.
This confused me as I thought maybe there was a mixup and some unix binaries had got packaged instead.
I ended up testing the 386 windows binary and it works fine after I added the missing extension.
Hope it helps, Fazl
ensure machine is connected to the Internet.
find or write a Markdown document that should generate a good TOC, e.g.
this gist.
use gh-md-toc
to generate a TOC for it, to stdout.
$ ~/bin/gh-md-toc ~/Desktop/burnout.md
Table of Contents
=================
* ["The Modern Day Sisyphus: \#libtech Burnout and You": <a href="https://twitter\.com/yo\_bj">Becky Yoose</a>](#the-modern-day-sisyphus-libtech-burnout-and-you-becky-yoose)
* [Abstract & slides](#abstract--slides)
* [twelve phases of burnout](#twelve-phases-of-burnout)
* [what's special about \#libtech burnout](#whats-special-about-libtech-burnout)
* [how to prevent/recover](#how-to-preventrecover)
* [\.\.\.but this isn't about what the victim should do](#but-this-isnt-about-what-the-victim-should-do)
* [co\-workers](#co-workers)
* [managers](#managers)
* [community](#community)
* [community privilege](#community-privilege)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
$
turn off networking
attempt to generate the TOC again.
only header is generated:
$ ~/bin/gh-md-toc ~/Desktop/burnout.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
$
gh-md-toc
5.0 built from commit 0523167dffc9cedcbc55996e3717716760bb4454Table of Contents
=================
* [Requirements](#requirements)
* [Installation](#installation)
* [Installation via Download](#installation-via-download)
* [Installation via Docker](#installation-via-docker)
* [Plain docker usage](#plain-docker-usage)
* [Usage on Synology devices](#usage-on-synology-devices)
* [Setup](#setup)
* [Configuring the database connection](#configuring-the-database-connection)
* [Remarks](#remarks)
* [Demo mode login](#demo-mode-login)
date: illegal option -- -
usage: date [-jnRu] [-d dst] [-r seconds] [-t west] [-v[+|-]val[ymwdHMS]] ...
[-f fmt date | [[[mm]dd]HH]MM[[cc]yy][.ss]] [+format]
sed: 1: "/<\!--ts-->/,/<\!--te-- ...": extra characters at the end of d command
sed: 1: "Installation-and-setup.md": invalid command code I
!! TOC was added into: 'Installation-and-setup.md'
!! Origin version of the file: 'Installation-and-setup.md.orig.2018-04-27_130143'
!! TOC added into a separate file: 'Installation-and-setup.md.toc.2018-04-27_130143'
here is an example:
root@myserver:~# cat /etc/redis/redis.conf | grep keep
# TCP keepalive.
tcp-keepalive 0
the above markdown snippet triggers an TOC entry:
* [TCP keepalive.](#tcp-keepalive)
which is wrong. the TOC should not generated based on the indent block.
Really useful idea.
Unfortunately it doesn't seem to work on Arch Linux with either Bash/ZSH at the moment. I can try out the go-based version in the meantime, but just thought I would report in case it is an easy fix to extend support beyond Ubuntu.
Just let me know if there is any other info you need.
make_test_output.txt
$ gh-md-toc --version
0.4.6
$ bats --version
Bats 0.4.0
$ zsh --version
5.2
$ bash --version
4.3.42
make test
...
9 tests, 6 failures
make: *** [Makefile:6: test] Error 1
For example, for the document:
title
=====
h2
--
### h3
...
### h3 2
...
### h3 3
...
h2 2
----
...
The TOC generated is:
$ gh-md-toc test.md
Table of Contents
=================
* [title</h1> <h2> <a id="user-content-h2" class="anchor" href="#h2" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h2</h2> <h3> <a id="user-content-h3" class="anchor" href="#h3" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h3</h3> <p>...</p> <h3> <a id="user-content-h3-2" class="anchor" href="#h3-2" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h3 2</h3> <p>...</p> <h3> <a id="user-content-h3-3" class="anchor" href="#h3-3" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h3 3</h3> <p>...</p> <h2> <a id="user-content-h2-2" class="anchor" href="#h2-2" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h2 2](#title)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
Test case: https://github.com/trailofbits/algo/blob/master/docs/troubleshooting.md
$ ./gh-md-toc troubleshooting.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
This returns an empty TOC: $ gh-md-toc "x:-y.md"
.
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
This works: $ gh-md-toc x-y.md
.
I have a README.md
I wanted to create TOC
wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc
chmod a+x gh-md-toc
cat README.md | ./gh-md-toc -
Sometimes it shows the contents, but sometimes it return blank. I cant understand why sometimes it works and sometimes not
Running on the local source of stoptracking/windows10/blob/Virt/README.md
.\gh-md-toc.exe --debug C:\Users\xxx\xxx\xxx\xxx\xxx\README.md
Table of Contents
2020/05/11 14:51:41 Convert2HTML: start.
=================
2020/05/11 14:51:41 IsRemoteFile: true
2020/05/11 14:51:41 Convert2HTML: remote file. content-type:
2020/05/11 14:51:41 Convert2HTML: done.
2020/05/11 14:51:41 Get c:\Users\xxx\xxx\xxx\xxx\xxx\README.md: unsupported protocol scheme "c"
Am I doing something wrong here? No idea why file type is identified as "remote".
$ git clone [email protected]:ekalinin/github-markdown-toc.git
$ cd github-markdown-toc.git
$ ./gh-md-toc README.md > a.md
this command returned after least one minute on Mac OSX 10.10.3 .
Does this project solve the basic problem:
Some kind of build step is needed to create the TOC.
I use this README to have a small wiki with version control.
I like editing the page via the github text editor (without local checkout and commit+push)
Can your project create a TOC without a build step?
It would be nice to have a mode like --insert
except instead of overwriting the existing file, the entire new contents of the file (not just the TOC) are output to standard output. Unlike --insert
this could work on non-local files, and allow another script to upload the file. It would also let you work on local files saving the result somewhere else and avoiding the next to create the .orig. and
.toc.` files which need cleaning up in scripts.
If my titles are URLs. E.g.:
Then the generated markdown will keep this URL in the TOC. So when I click on the TOC link I got redirected to the URL
TOC creating from STDIN on Mac OS X without GNU coreutils will fail, the error raised out like below:
$ cat foo.md | gh-md-toc -
gh-md-toc: line 144: $gh_tmp_md: ambiguous redirect
It fails because the mktemp command shipped with Mac OS X comes from FreeBSD, witch has different behaviour from the GNU coreutils one.
$ mktemp
usage: mktemp [-d] [-q] [-t prefix] [-u] template ...
mktemp [-d] [-q] [-u] -t prefix
I've send a pull request to fix this.
# First
### Third
becomes
* [First](#first)
* [Third](#third)
and github renders it in one line (see https://github.com/elimohl/test/blob/master/README.md)
I have a private repository and I want to use this generate a toc
Hi,
In sublime text there is a package called 'MarkdownTOC'. If can get that existing sublime package's python code to call and invoke this program, then it will auto-regenerate refresh the TOC on every save (Ctrl+S) in Sublime Text.
And that would be awesome.
Because currently MarkdownTOC does the hooks thing well. But not generate TOC correctly (which is very bad output actually). Need the best of both worlds.
I tried to generate TOC gh-md-toc https://github.com/pavelsr/coding_standarts/wiki/Perl
Seems like gh-md-toc
return non-encoded uri, that's why TOC does not work.
E.g. istead of link #Как-быстро-выучить-perl-
there must be #%D0%9A%D0%B0%D0%BA-%D0%B1%D1%8B%D1%81%D1%82%D1%80%D0%BE-%D0%B2%D1%8B%D1%83%D1%87%D0%B8%D1%82%D1%8C-perl-
So we need to add url escaping
It seems gh-md-toc(the repository version and other versions fails with it)
gh-md-toc https://github.com/iogf/untwisted/blob/master/BOOK.md
On XXX #XX, 2020 at ##:## (UTC) your personal access token (...) using gh-md-toc v0.6.1 was used as part of a query parameter to access an endpoint through the GitHub API:
https://api.github.com/markdown/raw
Please use the Authorization HTTP header instead, as using the
access_token
query parameter is deprecated and will be removed July 1st, 2020.Depending on your API usage, we'll be sending you this email reminder once every 3 days for each token and User-Agent used in API calls made on your behalf.
Just one URL that was accessed with a token and User-Agent combination will be listed in the email reminder, not all.Visit https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api/#authenticating-using-query-parameters for more information.
Thanks,
The GitHub Team
Was able to generate TOC yesterday -- today it is not working... Not sure if something changed on my end, or upstream GitHub changed something...
➜ ~ gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
➜ ~ echo $?
0
Versions of utils:
➜ ~ uname -m
x86_64
➜ ~ curl --version| head -n 1
curl 7.47.1 (x86_64-pc-linux-gnu) libcurl/7.47.1 OpenSSL/1.0.1t zlib/1.2.8
➜ ~ grep --version | head -n 1
grep (GNU grep) 2.20
➜ ~ sed --version | head -n 1
sed (GNU sed) 4.2.2
➜ ~ sed --version | head -n 1
sed (GNU sed) 4.2.2
➜ ~ awk -W version
GNU Awk 4.0.2
Copyright (C) 1989, 1991-2012 Free Software Foundation.
...
Would it be possible to not back up the README.md using a command line switch? We already have git?
If the title has .
character, the link returned from the API(https://api.github.com/markdown/raw) will miss the .
character.
For example,
# a.b
The related content of the link will be:
href="#ab
However, the right content should be:
href="#a.b
GitHub wiki pages can have spaces in the name. This is not supported by gh-md-toc. Filenames cannot have spaces.
This is my first time to submit an issue.
Issue:
The first segment of code is into normal words in generated TOCs.
Example:
gh-md-toc should generate
* [Functions and Closures <code>def</code> <code>with</code> <code>as</code>](#functions-and-closures-def-with-as)
for
## Functions and Closures `def` `with` `as`
instead of
* [Functions and Closures def <code>with</code> <code>as</code>](#functions-and-closures-def-with-as)
🤥 pushaowei🍭 15:04 ➜ skill git:(master) ✗ ./gh-md-toc ~/notes/skill/README.md
Table of Contents
=================
Parsing local markdown file requires access to github API
Error: You exceeded the hourly limit. See: https://developer.github.com/v3/#rate-limiting
or place github auth token here: /Users/pushaowei/notes/skill/token.txt
🤥 pushaowei🍭 15:01 ➜ skill git:(master) ✗ ./gh-md-toc --version
0.6.0
./gh-md-toc: line 231: lsb_release: command not found
os:
cat: /proc/version: No such file or directory
kernel:
shell: zsh 5.3 (x86_64-apple-darwin17.0)
curl : curl 7.54.0 (x86_64-apple-darwin17.0) libcurl/7.54.0 LibreSSL/2.0.20 zlib/1.2.11 nghttp2/1.24.0
wget : GNU Wget 1.20 在 darwin17.7.0 上编译。
grep : grep (BSD grep) 2.5.1-FreeBSD
awk : awk version 20070501
sed : sed: illegal option -- -
usage: sed script [-Ealn] [-i extension] [file ...]
sed [-Ealn] [-i extension] [-e script] ... [-f script_file] ... [file ...]
If I create some headers like:
# Top
will be generated
## On <sub><sub>[Go to Top](#top)</sub></sub>
side of this page.
It does generates this:
- [Top](#top)
* [On <sub><sub>[Go to Top](#top)</sub></sub>](#on--sub--sub--go-to-top---top---sub---sub-)
Instead of this:
- [Top](#top)
* [On](#on-go-to-top)
This tool is great! I'd like to suggest this improvement: allow me to specify the deepest heading level I want to consider to build the TOC, e.g., --max-level 2, it will only consider # and ## headers, it will skip from ### or more.
Awesome utility. It would be nice to be able to have this read from STDIN or from a --file attribute.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.