ekalinin / github-markdown-toc.go Goto Github PK
View Code? Open in Web Editor NEWEasy TOC creation for GitHub README.md (in go)
License: MIT License
Easy TOC creation for GitHub README.md (in go)
License: MIT License
Describe the bug
Sends data to github. This should be made clear somewhere that the tool is doing this. It should also be possible to send to an internal github enterprise installation instead.
Additional context
See here:
github-markdown-toc.go/internals.go
Lines 105 to 111 in 8928564
{"message":"This API renders Markdown text up to 400 KB in size. The requested text is too large to render via the API.","errors":[{"resource":"Markdown","field":"data","code":"too_large"}],"documentation_url":"https://docs.github.com/v3/markdown/"}
I've installed the latest version with go get and it won't work with any files, e.g
gh-md-toc https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md
What was changed recently? It's completely broken now.
laoliu@anonemous:/mnt/c/Users/laoliu/Documents$ ./gh-md-toc tmp.md
Header: Vary=Accept
Header: Access-Control-Expose-Headers=ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Header: Strict-Transport-Security=max-age=31536000; includeSubdomains; preload
Header: Referrer-Policy=origin-when-cross-origin, strict-origin-when-cross-origin
Header: Content-Type=text/html;charset=utf-8
Header: Cache-Control=public, max-age=60, s-maxage=60
Header: X-Frame-Options=deny
Header: X-Content-Type-Options=nosniff
Header: Etag=W/"8f02416ae1ffe52316586208420aa1472f865feba8e4f1a8ad86c2f4f78dd577"
Header: X-Ratelimit-Limit=60
Header: X-Github-Request-Id=27AF:64C2:4C8D70:4F9C04:637430A9
Header: X-Ratelimit-Reset=1668562617
Header: X-Ratelimit-Used=1
Header: X-Commonmarker-Version=0.23.6
Header: X-Github-Media-Type=github.v3; format=json
Header: X-Ratelimit-Remaining=59
Header: X-Ratelimit-Resource=core
Header: Access-Control-Allow-Origin=*
Header: X-Xss-Protection=0
Header: Server=GitHub.com
Header: Date=Wed, 16 Nov 2022 00:36:57 GMT
Header: Content-Security-Policy=default-src 'none'
Created by gh-md-toc
laoliu@anonemous:/mnt/c/Users/laoliu/Documents$
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 0523167I don't specify a 1st-level head in markdown files because Jekyll creates one for me when I use the title:
directive. My typical markdown file looks something like this:
---
layout: post
title: My Title
---
### Saturday, May 28
#### KIN ➜ BOS
Amtrak Northeast Regional #66 departs Kingston Station at 6:17 am and arrives in South Station, Boston at 7:58 am.
MBTA transit to Logan Airport.
#### BOS ➜ ATL ➜ SFO
Delta Airlines #1801 departs at 11:00 am and arrives at 1:43 pm.
Delta Airlines #1923 departs at 2:35 pm and arrives at 4:45 pm.
Here is the output from gh-md-toc:
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
I expected to see a TOC. Am I doing something wrong?
Describe the bug
The app renders an empty TOC:
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
To Reproduce
v1.2.1
.# foo
## bar
hello
## baz
world
gh-md-toc ./your_doc.md
Expected behavior
TOC is rendered.
Environment (please complete the following information):
1.2.1
Additional context
Add any other context about the problem here.
Is your feature request related to a problem? Please describe.
New standard in Go is to be able to install executables directly with go install
Describe the solution you'd like
go install https://github.com/ekalinin/github-markdown-toc.go ...
Describe the bug
I download the latest release from https://github.com/ekalinin/github-markdown-toc.go/releases/download/1.2.0/gh-md-toc.linux.amd64.tgz. When I execute it, it prints not only toc to my console, but also some header strings like this.
Table of Contents
=================
Header: X-Commonmarker-Version=0.21.0
Header: X-Frame-Options=deny
Header: Referrer-Policy=origin-when-cross-origin, strict-origin-when-cross-origin
Header: Server=GitHub.com
Header: X-Ratelimit-Limit=60
Header: X-Content-Type-Options=nosniff
Header: X-Xss-Protection=0
Header: X-Ratelimit-Remaining=37
Header: Access-Control-Allow-Origin=*
Header: Content-Security-Policy=default-src 'none'
Header: Access-Control-Expose-Headers=ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, Deprecation, Sunset
Header: Strict-Transport-Security=max-age=31536000; includeSubdomains; preload
Header: Vary=Accept-Encoding, Accept, X-Requested-With
Header: Date=Wed, 07 Jul 2021 12:41:49 GMT
Header: Content-Type=text/html;charset=utf-8
Header: X-Ratelimit-Reset=1625662491
Header: X-Ratelimit-Used=23
Header: X-Ratelimit-Resource=core
Header: X-Github-Request-Id=83A2:32F4:3A83D97:6ECFA15:60E5A10C
* [heading1](#heading1)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
But when I use the binary executable file built from the source by myself, it prints correctly without the headers.
To Reproduce
gh-md-toc path/to/the/readme/file
Expected behavior
Do not print the headers.
Environment (please complete the following information):
Additional context
None.
it seems it escapes chars like '-', '.' when in sections.
for example
some editors have a way to navigate through markdown documents, vy uses the text between [title] to navigate to sections in markdown docs. is possible to remove that behavior of escaping those chars from the toc?
Mac OSX 10.11
$ wget https://github.com/ekalinin/github-markdown-toc.go/releases/download/0.4.0/gh-md-toc.linux.amd64.tgz
$ tar xzvf gh-md-toc.linux.amd64.tgz
x gh-md-toc
$ ./gh-md-toc --version
-bash: ./gh-md-toc: cannot execute binary file
This would prevent the program from outputting:
Table of Contents
=================
Not a bug of gh-md-toc
, but currently it can't create a TOC because the GitHub API response has changed.
It is not clear when this started. It appears that the anchor tag now contains the "aria-hidden
" attribute.
- <h1><a id="user-content-one" class="anchor" href="#one"><span class="octicon octicon-link"></span></a>One</h1>
+ <h1><a id="user-content-one" class="anchor" aria-hidden="true" href="#one"><span aria-hidden="true" class="octicon octicon-link"></span></a>One</h1>
To Reproduce
$ # Markdown to be ToC
$ cat sample.md
# One
Uno
## Two
Dos
### Three
Tres
$ # Print ToC
$ gh-md-toc ./sample.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
Expected behavior
$ # Print ToC
$ gh-md-toc ./sample.md
Table of Contents
=================
* [One](./sample.md#one)
* [Two](./sample.md#two)
* [Three](./sample.md#three)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
Environment:
gh-md-toc
Version: 1.2.0 (via homebrew and go install
)golang:alpine
)
gh-md-toc
Version: 1.2.0 (via go install)Additional context
$ gh-md-toc --debug ./sample.md
Table of Contents
=================
2022/08/24 13:54:59 Convert2HTML: start.
2022/08/24 13:54:59 IsRemoteFile: false
2022/08/24 13:54:59 Convert2HTML: local file: ./sample.md
2022/08/24 13:55:00 Convert2HTML: converted to html, size: 487
2022/08/24 13:55:00 Convert2HTML: write html file: ./sample.md.debug.html
2022/08/24 13:55:00 Convert2HTML: done.
2022/08/24 13:55:00 GrabToc: start, html size: 487
2022/08/24 13:55:00 GrabToc: matching ...
2022/08/24 13:55:00 GrabToc: processing groups ...
2022/08/24 13:55:00 Including starting from level 0
2022/08/24 13:55:00 GrabToc: done.
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
$ cat sample.md.debug.html
<h1><a id="user-content-one" class="anchor" aria-hidden="true" href="#one"><span aria-hidden="true" class="octicon octicon-link"></span></a>One</h1>
<p>Uno</p>
<h2><a id="user-content-two" class="anchor" aria-hidden="true" href="#two"><span aria-hidden="true" class="octicon octicon-link"></span></a>Two</h2>
<p>Dos</p>
<h3><a id="user-content-three" class="anchor" aria-hidden="true" href="#three"><span aria-hidden="true" class="octicon octicon-link"></span></a>Three</h3>
<p>Tres</p>
If changes to the API response are permanent, it may be necessary to modify the regular expression.
github-markdown-toc.go/ghdoc.go
Lines 145 to 148 in 92ed8d0
$ wget https://raw.githubusercontent.com/ekalinin/envirius/f939d3b6882bfb6ecb28ef7b6e62862f934ba945/README.md
[...]
2017-04-21 15:53:27 (10.1 MB/s) - ‘README.md’ saved [10028/10028]
$ ./gh-md-toc README.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
I get the same with the bash version:
$ ~/git/github-markdown-toc/gh-md-toc README.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
Interestingly, this one did work the first time I ran it.
$ ~/git/github-markdown-toc/gh-md-toc --version
0.4.8
$ ./gh-md-toc --version
0.6.0
Hmm, these do work (remote pages):
$ ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md
$ ~/git/github-markdown-toc/gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md
Describe the bug
I downloaded the Windows binary release to try out. It seems to succeed in converting the Markdown to HTML, but instead of printing a Markdown TOC, it prints a list of what appear to be HTTP response headers from GitHub.
To Reproduce
Example command:
gh-md-toc.exe Home.md --debug
I also tried using the --token
argument with my GitHub token, did not see any difference.
The file being used does have headings in the form of #
, ##
and so on.
Expected behavior
Markdown TOC, like the examples in the readme.
Environment (please complete the following information):
Additional context
Here's a complete copy/paste of the command line:
gh-md-toc.exe Home.md --debug
Table of Contents
=================
2022/12/08 20:26:46 Convert2HTML: start.
2022/12/08 20:26:46 IsRemoteFile: false
2022/12/08 20:26:46 Convert2HTML: local file: Home.md
Header: X-Commonmarker-Version=0.23.6
Header: Cache-Control=public, max-age=60, s-maxage=60
Header: X-Ratelimit-Resource=core
Header: Access-Control-Expose-Headers=ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Header: X-Content-Type-Options=nosniff
Header: X-Xss-Protection=0
Header: Content-Security-Policy=default-src 'none'
Header: Content-Type=text/html;charset=utf-8
Header: Vary=Accept
Header: X-Github-Media-Type=github.v3; format=json
Header: Access-Control-Allow-Origin=*
Header: X-Frame-Options=deny
Header: X-Github-Request-Id=<redacted>
Header: Server=GitHub.com
Header: Date=Fri, 09 Dec 2022 01:26:47 GMT
Header: Etag=<redacted>
Header: X-Github-Api-Version-Selected=2022-11-28
Header: X-Ratelimit-Reset=1670552242
Header: X-Ratelimit-Used=6
Header: Strict-Transport-Security=max-age=31536000; includeSubdomains; preload
Header: X-Ratelimit-Limit=60
Header: X-Ratelimit-Remaining=54
Header: Referrer-Policy=origin-when-cross-origin, strict-origin-when-cross-origin
2022/12/08 20:26:47 Convert2HTML: converted to html, size: 19997
2022/12/08 20:26:47 Convert2HTML: write html file: Home.md.debug.html
2022/12/08 20:26:47 Convert2HTML: done.
2022/12/08 20:26:47 GrabToc: start, html size: 19997
2022/12/08 20:26:47 GrabToc: matching ...
2022/12/08 20:26:47 GrabToc: processing groups ...
2022/12/08 20:26:47 Including starting frome level 0
2022/12/08 20:26:47 GrabToc: done.
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
I'd rather not post the entire converted HTML but I verified that it does have <h1>
, <h2>
etc. tags.
Great code. It would be nice if it would escape special characters that are in titles.
For example, this readme
https://github.com/opscode-cookbooks/iis
There is a field called
mod_*
The underscore and * should be escaped like:
* [mod\_\*](#mod_)
github-markdown-toc.go/internals.go
Lines 105 to 111 in 8928564
The GitHub emails that have been going out say that this will soon stop being supported, and consumers should move to Basic Auth.
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.
Run into some regression test failure when trying to build the new bottle for macOS Ventura, the error is the heading processing is not working as expected.
brew install github-markdown-toc
echo "# Header" > README.md
gh-md-toc --debug README.md
$ gh-md-toc README.md
Table of Contents
=================
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
Debug mode
|$ gh-md-toc --debug README.md
Table of Contents
=================
2022/11/07 21:16:37 Convert2HTML: start.
2022/11/07 21:16:37 IsRemoteFile: false
2022/11/07 21:16:37 Convert2HTML: local file: README.md
2022/11/07 21:16:37 Convert2HTML: converted to html, size: 237
2022/11/07 21:16:37 Convert2HTML: write html file: README.md.debug.html
2022/11/07 21:16:37 Convert2HTML: done.
2022/11/07 21:16:37 GrabToc: start, html size: 237
2022/11/07 21:16:37 GrabToc: matching ...
2022/11/07 21:16:37 GrabToc: processing groups ...
2022/11/07 21:16:37 Including starting frome level 0
2022/11/07 21:16:37 GrabToc: done.
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
This will not work (because it is treated as a code block?):
* [Process](#process)
* [Preparing your workstation](#preparing-your-workstation)
* [Known Issues](#known-issues)
* [ERROR\! Unexpected Exception: [Errno 12] Cannot allocate memory](#error-unexpected-exception-errno-12-cannot-allocate-memory)
This will work:
* [Process](#process)
* [Preparing your workstation](#preparing-your-workstation)
* [Known Issues](#known-issues)
* [ERROR\! Unexpected Exception: [Errno 12] Cannot allocate memory](#error-unexpected-exception-errno-12-cannot-allocate-memory)
Hello,
thanks for the tool.
There's one feature I'd really like in it: the ability to directly manipulate a Markdown file and inserting the TOC in a specific place, in order to make the update automatic.
Let's suppose a README.md like
## Hello
asdasdasd
## Table Of Contents
xyahdyshasyhd
### Other title
I'd like to do something like
gh-md-toc insert-toc-at "Table Of Contents" README.md
And I would get on stdout the FULL README.md, with whatever was inside the "Table Of Contents" replaced by the TOC:
## Hello
asdasdasd
## Table Of Contents
* [Hello](#hello)
* [Table Of Contents)(#table-of-contents)
* [Other title](#other-title)
### Other title
I suppose I could achieve a similar result in bash with awk/sed/similar tools, but IMHO this feature would be quite in line with gh-md-toc purpose.
I'm no go expert, but if you think you don't have time to do it but you would accept a PR for it, I can try coding it myself.
"Compiling from source" section refer to make get-deps
This target is no more available in Makefile.
The "Compiling from source" section should be reworked or removed.
pc:windows64
download:gh-md-toc.windows.amd64.tgz
powershell:./gh-md-toc.exe html.md
result:
copy it in my html.md
show in github is ok:https://github.com/taohy88/gitbook_learning/blob/master/font/html.md
Can't display normally in gitbook:https://taohy88.github.io/gitbook_learning/font/html.html
How to resolve it ?
Describe the bug
unable to generate TOC from markdown
To Reproduce
run gh-md-toc and is nothing. guess regex expression is unmatched.
Environment (please complete the following information):
Just like this issue #13 (comment),it can't deal with the remote files.
For example,(the sample code in README.md)
$ ./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.go)
My environment:
$ git --version
git version 2.21.0.windows.1
$ ./gh-md-toc --version
1.0.0
This would allow someone to skip the first header
I thought I fixed this but quite often you have to run setup <device>
twice in order ot get a proper install. For some reason this seems to be racey and the MBR or SYSLINUX Boot Loader doesn't get written correctly?
Describe the bug
When running the tool on a .md file, for some reason, it generates a TOC item for the YAML I have at the top of my file. When I was using the shell script, it didn't pick up the YAML and generate a TOC item.
To Reproduce
Use a .md file with YAML at the top and run the tool. The output shows the YAML code ad depth=1
Looks for an annotation in a markdown file that represents the TOC
Use markdown comments to indicate where the TOC is to be placed in a file.
A markdown file would look like this:
TOC START comment
the actual toc
TOC END comment
The logic steps are:
Walk files
For each .md
Find the TOC comment annotation in that .md
Create the toc.
Inject into the markdown one line below the TOC and another annotation of TOC END
Is your feature request related to a problem? Please describe.
The none golang version has the ability to insert the generated TOC into the markdown file.
It would be nice if the golang tool also did that.
Describe the solution you'd like
A clear and concise description of what you want to happen.
Like so:
gh-md-toc --insert examples/02/README.md
gh-md-toc: error: unknown long flag '--insert', try --help
Describe alternatives you've considered
I could do it manually but well i am hoping this is something everyone might need.
Additional context
This bug is caused by fd65dd8 and goes away if I revert that commit.
Running
gh-md-toc ../README.md
crashes.
iMac-TMP:github-markdown-toc.go joe$ /usr/local/Cellar/github-markdown-toc/HEAD-3959e2c/bin/gh-md-toc ../README.md
Table of Contents
=================
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x12ba246]
goroutine 1 [running]:
main.(*GHToc).Print(0x0)
/private/tmp/github-markdown-toc-20170703-12178-5ub0au/src/github.com/ekalinin/github-markdown-toc.go/main.go:28 +0x26
main.main()
/private/tmp/github-markdown-toc-20170703-12178-5ub0au/src/github.com/ekalinin/github-markdown-toc.go/main.go:265 +0xa9a
(lldb) r ../README.md
Process 12715 launched: '/usr/local/Cellar/github-markdown-toc/HEAD-3959e2c/bin/gh-md-toc' (x86_64)
Table of Contents
=================
Process 12715 stopped
* thread #1: tid = 0xae9b72, 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28, stop reason = EXC_BAD_ACCESS (code=1, address=0x0)
frame #0: 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28
(lldb) bt
* thread #1: tid = 0xae9b72, 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28, stop reason = EXC_BAD_ACCESS (code=1, address=0x0)
* frame #0: 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28
frame #1: 0x00000000012bc1ea gh-md-toc`main.main + 2714 at main.go:265
frame #2: 0x000000000102bb8a gh-md-toc`runtime.main + 522 at proc.go:185
frame #3: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
frame #4: 0x00000000012bc1ea gh-md-toc`main.main + 2714 at main.go:265
frame #5: 0x000000000102bb8a gh-md-toc`runtime.main + 522 at proc.go:185
frame #6: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
frame #7: 0x000000000102bb8a gh-md-toc`runtime.main + 522 at proc.go:185
frame #8: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
frame #9: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
(lldb)
Would it be possible not to create backups as a command switch? We're already using git so to me it doesn't make sense. But what do I know :)
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.