DEV Community

Cover image for README.md as a Personal Site
Jhon Paredes
Jhon Paredes

Posted on

README.md as a Personal Site

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
Enter fullscreen mode Exit fullscreen mode

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!

Top comments (13)

Collapse
 
kschach profile image
Kevin Schachter

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.

Collapse
 
snesjhon profile image
Jhon Paredes

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.

Collapse
 
rattanakchea profile image
Rattanak Chea

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.

Collapse
 
snesjhon profile image
Jhon Paredes

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.

Collapse
 
nabil828 profile image
Nabil M. Al-Rousan

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?

Collapse
 
emgodev profile image
Michael

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.

Collapse
 
snesjhon profile image
Jhon Paredes

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!

Collapse
 
christennguyen profile image
Christen

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

Collapse
 
snesjhon profile image
Jhon Paredes

Thank you Christen! :D

Collapse
 
ben profile image
Ben Halpern

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

This is simple and delightfully declarative.

Collapse
 
snesjhon profile image
Jhon Paredes • Edited

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

Collapse
 
darkwiiplayer profile image
𒎏Wii 🏳️‍⚧️

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?

Collapse
 
snesjhon profile image
Jhon Paredes

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.