Markdown Readme Github



Because GitHub's README styling is actually really nice

  1. You Can Use Svg To Work Around, Example Code (./path/example.svg): And Then Use Image Insert Way To Embed The Svg File In Any Other Markdown File,..
  2. Markdown/README.md At Master · Emn178/markdown · GitHub
  3. Markdown - Github: How To Embed A Gist Into README.md ..
  4. Markdown Readme Github Extension

Background

If you have a little side project, often you might want a simple landing page. The GitHub README rendering is really beautifully done: clean, simple and modern. The official GitHub markdown to HTML API generates the HTML code, but not the stylesheets necessary to make it look nice.

Using your GitHub README as the main landing point works great for open source projects, where your visitors are developers and are familiar with GitHub, as well as you have all the text right where the code, the Issues and PRs are. But for some projects this isn't ideal. I built this project within a few hours for myself to get WalkWithFriends off the ground fast, without investing in building an actual website, or using a bloated website builder.

Some issues you run into when using GitHub as your main landing page

  • Maybe your project isn't actually an open source project, so you can't just host a README on GitHub
  • If you want to link to just the README, you could append #readme to your browser URL (making the URL less pretty), or the visitor has to know they have to scroll down
  • The mobile page of GitHub is still pretty bad, and it only renders the first few lines, as soon as you have a logo and badges on your page, it doesn't render at all, unless the visitor hits View all ofREADME.md
    • Non-tech visitors don't know what's a README.md
    • The button is small, and people don't know what is
    • GitHub renders the GitHub Pulse below, something that doens't make sense for non-tech visitors
    • The URL changes from something nice like github.com/krausefx/fastlane to github.com/krausefx/fastlane/blob/master/README.md, meaning you can either link directly to this page to have a nice content, or you link to the root page and have the downside of the extra buttons
    • Nat announced, that they working on improving the mobile experience, which is great news for everybody :)
  • You can't use your own domain
  • If you use your own domain, you have to use GitHub Pages (which is excellent btw), but then you have to have HTML files ready, which is exactly what this project solves.

Solution

A simple script that converts a markdown (.md) file to a single HTML file, that includes all the HTML and CSS code inline, so you can host it anywhere.

  • There are a lot of free online Markdown editors out there, so choosing one to use can be difficult. In this post, you'll find the top ten free online markdown editors. We think two truly stand out.
  • Markdown documentation: GitHub Flavored Markdown.

It's unclear to me what the format is, if there's systematic/command-line requirements for creating it, etc.Basically, just to need to know the specs, and if there's technical steps for generatin.

Github

There is no need to use this script if you already convert your markdown file to HTML, you can directly use the stylesheet of this repo.

How it works

This project doesn't actually use the GitHub stylesheet, it's far too complex, and has legal implications. Open anydesk.

Instead this project does 2 things:

  • Convert the Markdown to HTML using showdown, the most popular JS markdown parser. This could be replaced by the official GitHub markdown to HTML API
  • Inject the GitHub-like CSS code at the bottom of the page

Resulting you get an HTML file that contains everything needed, so you can host the page on GitHub pages, AWS S3, Google Cloud Storage or anywhere else.

  • Check out the original markdown file of this README
  • Check out the raw generated HTML code generated based on this markdown file on
  • Check out the GitHub rendered README
  • Check out the README rendered by this project

Usage

This will read the README.md from your current working directory and output the resulting HTML as README.html to the same directory.

Open tasks

Check out the open issues, in particular code blocks currently don't support syntax highlighting, however that's something that's rather easy to add. For a minimalistic stylesheet we could take the styles from krausefx.com css.

Playground to test

  • Bullet list item 1
  • Bullet list item 2
    • Bullet list item 2.1
    • Bullet list item 2.2
  1. Numbered list item 1
  2. Numbered list item 2

Inline code comments are 100

Quoted texts are more gray and look differently

You Can Use Svg To Work Around, Example Code (./path/example.svg): And Then Use Image Insert Way To Embed The Svg File In Any Other Markdown File,..

Bold text is bold and inline links work as well.

Header 2

Header 3

Header 4

Header 5

Normal text content again, lorem ipsum

Text 1 Text 2 Text 3
Text 1 Text 2 Text 3
Text 1 Text 2 Text 3

🔰 Raw HTML code for custom style 🔰

Introduction

When I create a Github repo, I try to make sure it's readme has at least one of the following elements:

  • An introduction (What's the project about?)
  • Table of contents (List me all your readme, so I can skim it and see if I'm interested or is what I'm looking for)
  • Some design love (A logo, icon, teaser or screen, README's with images look so much better.

Example

How to.. make an introduction

No brainer, but make sure it's an introduction, the same way papers have an abstract. I usually go for the following syntax:

The first uses the '#' tag, followed by the blockquote '>' tag and finally an horizontal line to separate it. Use the < hr > tag (yeah, markdown supports it! I separated it here because Coderwall parses it).

How to.. make a table of contents.

Example (works in coderwall too, test it!) -

Markdown/README.md At Master · Emn178/markdown · GitHub

Separate the topics your repo talks about with the '#' tag, and then use the following syntax to add your table of contents (if you are lazy like me, go to this Gist and copy the example):

Readme

(In Github, you don't need to put the a name tag. It parses the h1 tags with a hyphen, so if they are named the same as your table of contents, you don't need to do anything else. In other places cofCoderwallcof you need to force it with the empty A tag)

How to.. add images to a README.

Markdown - Github: How To Embed A Gist Into README.md ..

You may not be strange with the familiar of the '!' followed by the alt name property in brackets and then parenthesis with the link.

It's the same in Github, but in order to properly display it properly, you need the RAW file. Create an assets folder, add your images there and use the RAW path in your project. You can even use other Github repo's images as long as they are Publics!

That's all folks. Any other Github beautiful tips?

Markdown Readme Github Extension

Related protips: