Recover any GitHub README.md and well printed it to had a beautiful documentation site.

Software documentation is a lie: nobody wants to do it but everyone wants to have it.

We can't write your project documentation, but we can help creating a bridge to reduce the quantity of time you need to setup a beautiful documentation portal.

Nowadays is very common use git to control version over text. For example, take a look at RFC spec for the next web API, or any of the TC39 Proposals.

That's a great thing, but you are limited to see the documentation based on how GitHub decides to render the markdown frontend layer.

In addition, you need to browse GitHub each time, adding a lot of noise that is not related with what you want to do: read the spec.

Normally, when a project tends to growth, they decide to create their own documentation portal using tools like Docsify or Docusaurus.

The problem with these tools is that they are in the other point of friction: They add an extra layer of maintenance that could be unaffordable for many projects.

You just want to read docs, and you want people to spend more time writing than by keeping the documentation portal.

We want to create a zero configuration documentation portal for any project. This means there's no friction on publishing your own documentation online.

For doing that, we are going to use GitHub as backend.

That's a limitation, but also an advantage: If your documentation file is on GitHub, we can recover it.

After that, we want to render the markdown file alone in a portal. Just documentation, no more.

The zero configuration means you need to do nothing additional: The site portal will be minimal with good defaults to render any document. That means a lot related to visual text rhythm, space between lines, typographies, etc.

If you wish you can modify the defaults visual settings to adapt your documentation and feeling it a bit different from the rest.

Some emoji legends:

• 🚧 WIP
• ✅ Done
• ⛔️ Blocked
• ▶️ On Road

The goal of the first iteration is to set up a public website for reading any documentation file hosted on GitHub.

📖 Naming Things

"Readme Project" is a codename. We need to determinate what is the public name of the project and associate an

Some ideas are:

• read.me
• readme.md
• lee.me
• lea.me
• help me please
• re.read

The problem with this kind of name is they are already taken, so need to determinate one enough good that transmit the project message but didn't take yet.

That includes:

• Choose a Name – Should be easy to pronounce in English.
• Choose a Logo – Should be readable as favicon, Name + Logo and Name + Logo + Claim.
• Choose a Claim – Should something minimal that resume the project (eg: Pretty README as service).
• Choose a typography.

Main inspiration: DocumentUp.

We are going to use GitHub as backend for recovering the target README.md.

For do that, we are going to determinate the file that we are interested in recover based in the URL route.

For example, if our site is called read.me, then the file to recover match with GitHub url using org/repo schema.

If we want to see

github.com/drufball/layered-apis

it matches with

read.me/drufball/layered-apis

For do that, our folks from Algolia have a public index with all GitHub documentation repositories normalized.

It's the same index that they use at yarn website to recover the README.

• Algolia Public Index.
• TextMe – lightweight JavaScript utility to create self-rendering Markdown + LaTeX documents.
• micro-react – Create microservice apps with React components.
• md-page – create a webpage with just markdown.
• Marked – Micro service for markdown rendering.

Main inspiration: Medium.

That's one of the most critical goals of the project.

The visual look and feel of the site need to be enough good to read any document with good quality.

Take for example any Medium post as example.

Why is it so popular even exists other blogging platform more powerful? Sensible good defaults: Any thing that you write on Medium, looks pretty.

That's include:

• Choice a white color palette as base.
  • Open Colors Scheme.
  • Dark Palette.
  • Carbon Design System (click dark mode on bottom).
• Choice a paired font to use.
  • fontpair
• Ability to switch to Dark mode & remember preferences (#2).
  • Building the N26 Dark Mode
  • Redesigning your product and website for dark mode
  • How to detect if OS X is in dark mode in browsers?
  • Using dark mode in CSS with MacOS Mojave.
• Copy Clipboard button for any code block (#2).
  • codecopy – "Copy to clipboard" button for your code snippets.
• Show on GitHub button in the corner. – GiHub Corner – Add a Github banner to your project page.

In the same README location, make possible load custom settings if readme.json is detected.

These settings could be also encoded at query-state

• Setup theme color

Main Inspiration: Microlink SDK

Add the ability to see a link preview on hover.

Main Inspiration: Clap Button

Now we have a functional site, it's time to start bringing up some sugar things in order to improve the user experience.

We can translate the Clap button by Medium, but using the GitHub way, this means, the button reflects the ⭐️'s.

Another things we can add after the star button could be

• Visit GitHub repository
• Watch/Unwatch
• Share

Main Inspiration: Twitter Threads

Add the ability to add comments. The comments works similar to Twitter Threads, where the started point is a previous sentence writtent in the documentation.

The comment can be created using your GitHub credentials.

Inspiration:

• https://github.com/aroc/side-comments
• https://github.com/jimpick/lambda-comments
• https://github.com/skx/e-comments/
• https://github.com/kevinweber/inline-comments
• https://github.com/flpvsk/react-commenter/
• https://www.producthunt.com/posts/ouija
• https://github.com/netlify/gotell
• https://github.com/netlify/netlify-comments-starter

Main inspiration: usefathom.com.

Now we have a public portal site for reading any documentation, we can provide public insights for know more about web traffic.

The analytics insights are provided by GitHub as well but it's only available for maintainers and it's very limited.

The idea is make this information public by default: Just add + in your URL for see stats.

For example: read.me/drufball/layered-apis+

• https://demos.algorithmia.com/github-readme-analyzer/
• Show the number of concurrent readers. [1] [2].

Allow to hosted your own microservice for connecting it with your GitHub Enterprise.