Use a Github Profile — or others README files — as Static Website
In 2020 Github released a feature where its users can define a README.md file and have it rendered on their Profile Page. The markdown is rendered as html front and center on github.com/<username>.
This awesome feature gives users the opportunity to create a landing page for their developer persona to share information and present their work. And it seems to have been well received by the community — you can find many awesome examples in repos like abhisheknaiidu/awesome-github-profile-readme and github.com/coderjojo/creative-profile-readme.
My Github Profile
A few weeks ago I finally got around to create my Github Profile Page. I had a lot of fun using image shields and custom html to list technologies I liked, as well as a tracker of my active Github projects.
I was happy with the outcome, but it also got me thinking… Could I use this page as a personal landing page? I have been using a Hugo + Netlify static website for my personal website, gtalarico.com. And while I liked Hugo, I always found a bit painful to make changes to the website content and structure. Github markdown editing lets you see live a preview, and the constraints of Markdown forced me to keep the content simple.
What if I could use my Github Profile, hosted and editable on Github, but rendered as an html website outside of Github?
# markdown.is
markdown.is is a simple static website that extracts parameters from the URL path to find a markdown file, and then renders it into the page.
For example, I can render my Github Profile page github.com/gtalarico/gtalarico/README.md by going to markdown.is/gh/gtalarico.
I could also render a project README by pointing to a specific repository — markdown.is/gh/gtalarico/pyairtable renders github.com/gtalarico/pyairtable.
Use Cases
Github Profile as a Website
This is the primary use case illustrated above. For example, you can include markdown.is/gh/usernamein your twitter or instagram profile to have viewers see your profile page as nicely rendered page, without all the other Github content and context.
Other Markdown Files as a Website
You can also use this to create a clean render of a Markdown to use it in a presentation, or to be able to render anything that doesn’t require knowledge of the repository. This is a nice way to link to or browse repos like awesome-* .
Features
URL Routing
By default, markdown.is attempts to render the Github Profile page of the provided username. For example, markdown.is/gh/gtalarico will render github.com/gtalarico/gtalarico/main/README.md
To render files in other repositories, just append the repo name to the URL path. For example, markdown.is/gh/gtalarico/pyairtable will render github.com/gtalarico/pyairtable/main/README.md
Branch Selector
The default branch is main. If you want render a different branch, you can provide the branch name as a URL query param markdown.is/gh/gtalarico/pm?branch=master
Custom URL: Alias
You can create custom alias by submitting a PR adding your alias to src/config.json . For example adding markdown.is/gui will render my Github profile.
Custom URL: Domain Redirect
You can also configure your own domain to redirect to your markdown.ispage by changing your DNS records. Below we configure gui.is to redirect to markdown.is/gui.
Styling (Beta)
In addition to rendering your markdown, you can also apply custom css styling. You can do so by adding a CSS file README.css next to your README. After the page loads, the CSS will be fetched and injected.
Credits
The page uses DOMPurify to sanitize the markup, markdown-it to render the markdown as html, and github-markdown-css to style the markup.
Final Notes
markdown.is is in its early development. Contributions in the form of ideas, feedback, or code improvements are welcome. The project is free and open-source and the source code is available at github.com/gtalarico/markdown.is.
