loading...
Cover image for README.md as a Personal Site

README.md as a Personal Site

snesjhon profile image Jhon Paredes ・3 min read

After reading this article Evolution of My Personal Site I recalled how often I’d change my personal site as well. Most of the time I’d adopt a new framework with a new design. But I was always dissatisfied.

I found that by the time I’d setup the site, chosen a theme, figured out the workflow (not to mention wrangle all the dependencies) I’d already be disinterested with how I’d update this site continuously.

I wanted something simpler.

Here are the requirements I was looking for:

  • Minimal setup

    • I didn’t want to deal with components, routers, boilerplates.
    • Local dev workflows are nice, but it depends on how often you'd envision updating this site. For me, it wasn't very frequent.
  • Clean/Simple Theme

    • I enjoy tinkering with themes, but I just wanted to manipulate a couple of simple css rules and be on my way.
  • Easy to publish -- Anywhere.

    • Just push and publish. On my local or phone.

Most recently I'd gone through the personal site rabbit hole with GatsbyJS. Although it's a great package -- again, by the time I'd setup everything I'd given up on keeping up with the site.

Sometimes too many options is not what everyone wants.


Inspiration

While reading the dev.to README.md I was struck with how pleasant it must've been to write it.

Not only was it clear, but it conveyed enough information to get the developer started.

So I figured there must be a way of just converting a simple README.md file to a full fledged website and just use that as my personal site. One caveat -- I wanted what I saw on the markdown to be the website. Not another theme or styling, just Github Flavored Markdown style.

Welp. Not so simple.


Github Pages, Gitlab Pages + showdown.js

Here are my current options when trying to convert a markdown to a personal site. (disclaimer: I'm not saying any of these services are bad -- they just didn't fit my use case)

Github Pages

  • As detailed here, you're able to upload a markdown file and have that as a Github Page.

  • However, Github Pages are closely tied with Jekyll Themes. They also add a title and header that aren't part of the markdown file. I had to use css to hide unwanted parts of the jekyll theme.

Gitlab Pages + showdown.js

  • Gitlab Pages were another option as they have a commit & push pipeline runner. Which is great because I could utilize any markdown cli converter to publish an index.html.
  • After searching on many, many converters I found that they were great when you wanted to output html -- but not a complete index.html. That makes sense as they were built to output to a surrounding framework.

So why not just a simple html file?

As I learned from the @dstarner blog, sometimes it's best to keep it simple. I wrote up a simple index.html file, added GFM css, and was done!

But -- well -- have you tried to write html on your phone. It's not the most pleasant experience. Why can't I just write markdown?


(Over)Engineering a Solution

I'm thoroughly convinced that 96.4% of all npm modules were written because someone couldn't solve their problem so they wrote it themself.

SO! I wrote a small cli to solve my problem.

I called it singlemd and it accomplishes exactly what I want wanted.

My website is now just a simple markdown file, which I can modify anywhere. And with Gitlab Pages pipeline I can add a .gitlab-ci.yml

image: node:8.12.0 

pages:
  cache:
    paths:
    - node_modules/

  script:
  - npm install singlemd -g
  - singlemd --input ./README.md --output index.html --style ./public/style.css --title "snesjhon | Jhon Paredes"
  - mv index.html ./public
  artifacts:
    paths:
    - public
  only:
    - master

And anytime I update my README.md my website is updated. FUN!

Lessons

This is the first npm package that I've published and I'm glad that it was something that I'm actively utilizing. Lots of work left to do, but overall a great experience learning how to create + publish a cli package.

Thank you for reading!

Posted on by:

snesjhon profile

Jhon Paredes

@snesjhon

Just a kid from Oakland walking around and believing in fairytales.

Discussion

markdown guide
 

Looks great! Thanks for writing this (the post and the Node app).

A couple questions for you:

  • RE: "Local dev workflows are nice, but it depends on how often you'd envision updating this site." do you mean something like using Jekyll to compile static HTML pages locally as a local dev workflow?
  • In the sample README.MD, did you add the beginning HTML with the singlemd header manually or is that generated from Markdown by the app?

I've been using Jekyll for a simple blog for my thesis writing and I like it but it seems overkill for a single page. I like the idea of the GitLab pipeline a lot vs. having to build the site and then push.

 

Hi Kevin, thank you for your feedback!

Regarding your questions:

  1. Yes, that's exactly what I meant. I had to run my local server, wait to compile, (update packages if needed), change content, commit, and push. I just wanted to change my content and push. Plus be confident that whatever markdown editor (albeit with GFM) would reflect how my page would look like.

  2. I added that html myself. I took inspiration from bootstrap's README to center the title header. Since markdown accepts a limited amount of html I can manipulate certain positioning without having to resort to css.

Using Gitlab Pipeline has been great to automating my personal site's development flow -- since I only have to worry about my content. Hopefully Github Actions will work in a similar fashion and can extend to Github Pages.

 

I have been looking for sth similar for simple and easy to maintain website. I am not sure if it is possible to add custom class name into Markdown file and render into html? That would be great to apply styling to specific area.

 

Hi Rattanak,

I'm not sure if I'm answering your question correctly, but each markdown output will be within an <article class="markdown-body"> which you can then add any style that you wish. Since cli allows you to add a custom css which will be inserted after the GFM style.

If instead you're referring to adding something like:

{:.nameofclass}
paragraph is here

I'm not sure if markdown-it (the markdown parser I'm using) would support it. Feel free to add an issue to discuss further.

 

Hi Guys, excellent work. The demo's repo is hidden I think. I am wondering how to make the markdown responsive as in the personal site. I am Bootstrap noob. Do you insert html code in the readme file to make the markdown responsive?

 

This is interesting. I have been trying to build personal blog solutions for this very purpose. I first started web development writing blog files as JSON and ajaxing them into my site (when it was a single page site) and later on with PHP JSON parsing (when it was a PHP site). Lately I am working on a node version of my site which uses a markdown library, while the other pages are still EJS templates, the blog posts are rendered markdown pages.

Looking forward to following your article later in free time to give this a try myself, not sure I'm fond of making the entire website as markdown though.

 

Hi Michael,

Thank you for the feedback!

I was definitely hesitant at first with developing with just markdown. There's a lot of limitations that come with this approach. But within those limitations I found myself being at ease with not continuously "optimizing" my workflow.

I'd be interested to see what you come up with. Always looking to improve the personal site process. Good luck!

 

Awesome article Jhon! It was a great read! :)

 
 

This was a very pleasant read itself. A really interesting train of thought and outcome.

This is simple and delightfully declarative.

 

Hi Ben, thank you very much for your kind comment! :D

 

sooo... Couldn't you have used something like sed to replace a string like <!-- content goes here --> in a template file with the rendered markdown?

 

Hi DarkWiiPlayer,

Yes, I could've definitely done that. But I also wanted the flexibility to manipulate the template file using a single line in the cli. Like adding custom css or changing the title.