krausefx / markdown-to-html-github-style Goto Github PK

View Code? Open in Web Editor NEW

215.0 5.0 128.0 1.03 MB

Generate a simple HTML page based on a markdown file, that looks like GitHub's stylesheet

Home Page: https://krausefx.github.io/markdown-to-html-github-style/

License: MIT License

JavaScript 17.73% CSS 21.17% HTML 61.10%

markdown-to-html-github-style's Introduction

Markdown to GitHub style web

Because GitHub's README styling is actually really nice

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 of README.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 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.

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

Dependencies

npm install

Usage

node convert.js MyPageTitle

This will read the README.md from your current working directory and output the resulting HTML as README.html in 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

{
  testcode: 1
}

Bullet list item 1
Bullet list item 2
- Bullet list item 2.1
- Bullet list item 2.2

Numbered list item 1
Numbered list item 2

Inline code comments are 100

Quoted texts are more gray and look differently

Bold text is bold and inline links work as well.

Header 1

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

markdown-to-html-github-style's People

Contributors

Stargazers

Watchers

Forkers

farazpatankar huri000 wazum joelz stefma midyan owencook woytek-polnik titan2351 justlester bhaal22 cincong samraj1980 adwolfart davporte cjdoris robertomalatesta ptsang1 jeepeo lbrochini m-saravanan royblueky olaho maryam1710 hero-007 sn8keyes311 pex-1 shettigarsanthosh re-savior drewharshaw haodaz sahilbajaj-roposo sajijola1 franxifra patrick-gourdet redhab priya1114 avimuk coddit xpanella ppambler vanphong helderm01 jeffreyho101 suvink irinagain rahul-mishra-coder demonslayer10 micpob diyaannathoma2 fernandobdansi chen-keinan atefdodo bahareharandizade catekat16 williamjqk mjk134 bhagydeep24 volkantagal hsgaurav hmrg-grmh sasha-uk lucasalesterio jrnewton prones94 sam-1210 haalibrahim melvynph bharath2408 nasrij e-oliveira jayeshmax erickkf600 loressl yakubouski qnreck akankshvee tnkompanska19 simon-xu-lan erickonieczko-toast jeeshan12 feldrise billwang115 changsen-dev monsieurduke ujwalamusku eoinbrennan2000 wdoconnell prantaneel alu0101320779 pellerano salunkhebhushan drobert31 jm-lemmi fcoyevenes yash-me hatimmansor fyevenes90 arbakker alforov-eugene

markdown-to-html-github-style's Issues

Add nice style for hr nodes

---

looks pretty bad right now, take the design from krausefx.com or github.com

(feature request) footnotes support

One of my favorite features of GH markdown is footnotes. Here's an example article of mine that makes extensive use of them. Would it be possible to add support for these to this project?

Open links to external hosts in new tab

Use target=_blank for all links that link to another domain. This will require knowledge of its own domain, for absolute URLs going to its own domain. Might be good enough without specifying its own host, and assume relative URLs

Improve support for images

I haven't had the time to test this yet, but images on GitHub behave quite nicely. It might be that this project doesn't properly render images yet

Add mobile support

How to automatically use your style.css

Dear Felix,

Thank you for providing this repository!

For our bioinformatics work at the DRESDEN-concept Genome Center, we started to write Markdown files to provide READMEs to our collaborators. We are currently using Gitlab for that, and wrote our first CI/CD script to automatically generate HTML and PDF files when a Markdown file has been changed.

The basic pandoc-generated files look pretty ugly, so I started to play around to make them prettier. I followed your recipe today, and ran into a question.

First, I tried pandoc --standalone --css="style.css" (and various versions of it), but it would not incorporate the CSS file properly.

Then, I pretty literally followed your advise and automatically "injected" the content of your style.css file to the end of the basic pandoc-generated HTML file. That worked!

# Convert Markdown to HTML 
pandoc --standalone --from=markdown --to=html $file -o "doc/${id}.html"

# Add CSS at the bottom of the HTML
# Remove last two lines
mv doc/${id}.html doc/${id}_orig.html
head -n -2 doc/${id}_orig.html > doc/${id}.html

# Inject CSS file
echo "<style type='text/css'>" >> doc/${id}.html
cat style.css >> doc/${id}.html

# Close blocks again
echo "</style>" >> doc/${id}.html
echo "</body>" >> doc/${id}.html
echo "</html>" >> doc/${id}.html

It looks so much better than before, but I still wouldn't get the same text width (it looks quite narrow) and am missing the outer border. Would you have any idea?

Thanks a lot in advance!
Best wishes from Dresden :)
Katrin

Table is rendering as markdown

Add a way to stop processing markdown once the Development section is hit

This way it allows you to keep the project README focused on both the product landing page, as well as development specific instructions. This could be as simple as looking for the

## Development

section, allowing the user to specify what header to look for what

Make this project usable by providing a CLI

Right now it's mostly a proof of concept, because I needed it for myself for WalkWithFriends.net, this CLI should provide options for an input and output path, and be distributed via a dependency manager to actually include this in a project.

Since most of this project is just the style.css file, we could easily add multiple implementations, like Ruby, to make it easy to integrate it into all kinds of projects.

Using __dirname for export filename makes no sense

The script should use process.cwd() (the current directory) instead for finding the README and writing the index.html
(or ask for it)

<meta charset="UTF-8"> by default?

It seems to be a de facto practice on modern web sites to use UTF-8, i.e.

<head>
  <meta charset="UTF-8">
</head>

This way one does not need to write the awkward ä etc. codes to represent letter ä for example. Maybe it would make sense to have that meta tag be generated in all output by default?

"hljs" artefact in code environment?

Hi,

when I generate HTML from the following page:

```
Type :   Extensible
Order:   Significant
Root :   Yes
```

I get:

Where does the hljs come from? I have recent versions of markdown-to-html-github-style and showdown installed.

Thanks!
Michael

Add support for syntax highlighting

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.

There are many libraries that support syntax highlighting to HTML, some even come with nice stylesheets. We gotta find one that's similar to GitHub

Add option to make use of GitHub's official markdown parsing

To make sure it's fully compatible, we could make simple web requests to the GitHub markdown API

This will generate just the HTML code, not the CSS necessary