raychenon/play-table-of-contents

Web app to generate table of contents of markdown file. Built with Play Framework for Scala .

The hosting on "http://tableofcontent.eu" stopped due to costs of AWS.

Table of Contents

• Introduction
• Online Generation
• Run locally
• Docker
  • Build
  • Run locally
  • Run on AWS Lightsail

Introduction

Web based table of contents generator

There are plenty of markdown table of contents generators on github, but the installation of the dependencies is a lot of overhead for an occasional activity. That's the idea of this web app.

In addition, it is a nice tutorial on Scala 😄

Online Generation

You don't need to install anything.
1 Go to http://tableofcontent.eu/
2 Copy paste your markdown content or your github repo link and click "submit" "

Run locally

You can run locally, go to the root project and enter this command line.

sbt run

By default, it will run on http://localhost:9000 .

To run on local on a specific port

sbt "~run 8081"

Docker

Build

At the root of the project, run the command line and pass in parameter your username on https://hub.docker.com/

$ ./build-docker-image.sh <DOCKER_HUB_USERNAME>

Run locally

See the last Docker image build

$ docker images

To run locally, use the cmd

$ docker run --name <CONTAINER_NAME> -p <FROM_PORT>:<TO_PORT> -d <IMAGE_ID>

# for examples :
$ docker run --name container -p 9000:9000 -d e2a451cb675f

The application will run on "http://localhost:9000".

To stop every Docker processes from running .

$ docker stop $(docker ps -a -q)

Then once the containers stop running, you can delete the containers.

$ docker rm $(docker container ps -a -q)

Run on AWS Lightsail

The instance is already set up. Go to the console and run this command:

$ sudo docker run --name toc -p 80:9000 -d raychenon/play-table-of-contents:<tag>

play-table-of-contents's Issues

Set Content Security Policy properly

Content-Security-Policy header is currently disabled
play.filters.headers.contentSecurityPolicy=null

Read https://developers.google.com/web/fundamentals/security/csp/ and enforce the security policy

Test coverage

Add tests especially in the table of contents generation logic ( TableOfContentHelper)
Use Specs2 .

Deploy with docker

Package in a Docker container to deploy on a cloud provider.

Indent incorrect if Heading contains #

# PKCS
# PKCS#11

is currently rendered as

**[Table of Contents](http://tableofcontent.eu)**
<!-- Table of contents generated generated by http://tableofcontent.eu -->
- [PKCS](#pkcs)
  - [PKCS#11](#pkcs11)

but it should have been

**[Table of Contents](http://tableofcontent.eu)**
<!-- Table of contents generated generated by http://tableofcontent.eu -->
- [PKCS](#pkcs)
- [PKCS#11](#pkcs11)

Escaping the hashtag leads to the same result...

Ignore the titles in code comment

Ignore anything that's contained by ```

# Full URL for authorization endpoint
# Maximum number of retries

Example : https://github.com/zalando-incubator/play-zhewbacca/blob/master/README.md

use a code formatter

Use a code formatter for Scala
https://github.com/scalameta/scalafmt

CD AWS CodeDeploy

After #41 CI/ CD pipeline -> Docker push , try with AWS CodeDeploy

upgrade to play 2.6 framework

Upgrade from Play 2.5 to 2.6.x
https://www.playframework.com/documentation/2.6.x/Migration26

• update to Play 2.6.3
• Scala Controller changes. No more play.api.libs.concurrent.Execution.Implicits.defaultContext . ExecutionContext has to be injected in constructor
• use compile time DI
• keep Netty as server
• fix the reusable block not displaying the github buttons https://www.playframework.com/documentation/2.6.x/ScalaTemplates

Integrate a copy paste and markdown highlighter

https://clipboardjs.com/ looks like a good candidate

Support reStructuredText

Would it be possible to support generating TOC for reStructuredText files too?

Better slugification

Link are incorrect with special chars, examples:

• promises::all([ mapper ]) → #promisesall-mapper- (#promises::all([-mapper-]))
• join(p1, ..., pn, cb) / join([p1, ..., pn], cb) → #joinp1--pn-cb--joinp1--pn-cb (#join(p1,-...,-pn,-cb)-/-join([p1,-...,-pn],-cb))

Improve UI design

• stop adjust the width of the textarea
• improve the UX on mobile
• package the assets in Docker

[UI] Suppress the bullet list

The bulleted list should not be displayed.
My knowledge is limited in CSS , help is welcomed

Compile Time Dependency Injection

Use a Compile Time Dependency Injection (CT DI ) library Macwire.
Now it is a manual CT DI

Add github buttons star and watch

After the table of contents is displayed, show the github buttons.
Use https://ghbtns.com/#star

Serverless ?

See if it is worth to run on serverless as it is idle most of time

Add favicon

Create a favicon "TOC"

create a CI/CD pipeline

such as https://bitbucket.org/product/features/pipelines

HTML should probably be escaped ;)

If the original Markdown code contain raw HTML (that is a purely acceptable syntax in markdown), it does not get escaped in the resulting output. One way around this would be to output to a textarea where HTML won't be rendered (it's also much easier to copy-paste then!)

Provide more options

Some options needed:

• 2 or 4 space indent - else list indentation does not work with 1 space indent in some displays.
• use fill link like https://github.com/sanskrit-coders/indic-transliteration/blob/master/README.md#scala rather than #scala (less important)

source raychenon/auto-toc#2

Optionally add [Back to top] links at the end of each section..

Will help navigation..

Set HTTPS

Make the site run on HTTPS
https://www.playframework.com/documentation/2.6.x/WsSSL