TOC (Table of Contents) generator

Table of contents

1. TOC (Table of Contents) generator
   1. Table of contents
   2. Description
   3. Programming language
   4. Build the project
   5. Usage
      1. Run it for only one file
      2. Run as webserver
   6. Build and run with Docker

Description

Generates the table of contents for a markdown document, based on its headings. Can be used in 2 ways:

• as a web-server accepting a URL path to the location of the document
• as a one off for local files or remote URL's

Programming language

Writen in GO

Build the project

git clone https://github.com/mehiX/ReadmeTOC.git
cd ReadmeTOC
go get -d -v ./...
# command line
go build ./cmd/cli/*.go
# http server
go build ./cmd/http/*.go

Usage

Run it for only one file

The path parameter can be a local file or a URL

./toc URL

Prints out the table of contents. This can be then pasted inside the original file.

Run as webserver

# Listen on 0.0.0.0:8080
./server :8080

The URL can be passed as a query parameter:

curl http://localhost:8080/query?path=https://raw.githubusercontent.com/mehiX/ReadmeTOC/master/README.md

or it can be send as part of a json request body:

curl -v -X GET \
  -d '{"url":"https://raw.githubusercontent.com/mehiX/ReadmeTOC/master/README.md"}' \
  -H "Content-Type: application/json" \
  http://localhost:8080/json

Build and run with Docker

# Build the image
docker build -t readmetoc:1.2 .

# Run as a webserver on host port 8888 (for example)
# The user inside the container is unprivileged so make sure to 
# use a port number > 1024
docker run \
  -d \
  --rm \
  -p 8888:1025 \
  readmetoc:1.2 \
  :1025

# Run the container for 1 file (local)
docker run \
  -t \
  --rm \
  -v $(pwd)/README.md:/tmp/README.md \
  --entrypoint "./toc"
  readmetoc:1.2 /tmp/README.md

# Run for a URL
docker run \
  -t \
  --rm \
  --entrypoint "./toc" \
  readmetoc:1.2 https://github.com/mehiX/ReadmeTOC/raw/master/README.md