New Website

I've made a new website, as lynx.io is dead. You can find it here: http://macr.ae/—it's similar in format to lynx.io, but has better articles, and they're all written by me.

JavaScript disabled

While it will still mostly work, a lot of this site's functionality relies on JavaScript - please enable it for the best experience.

lynx.io: Powered by GitHub

This article is the first in a couple articles on the new lynx.io website. This article is entitled "lynx.io: Powered by GitHub", and is about how we use GitHub's Pull Request mechanism to accept, review and comment on new articles.

Background

I recently rewrote the lynx.io website (then called lynxphp; I renamed it when I launched the new backend and design) so that I wouldn't have to use WordPress anymore. The new site uses PHP and quite a bit of JavaScript, and articles are written in MarkDown, which I prefer for writing over HTML or BBCode (GitHub also uses MarkDown for READMEs, and comments on issues and code). Articles are stored in static files in the articles directory and indexed by the articles.json file (again in that directory), which means that there is no need for a database at all. That was a bit tricky for stuff like searching and comments, but I will cover that in another article at a later date.

Adding articles manually

To add an article to the website, two things have to be done:

  1. Article file created and populated - except for an <info> section at the top of the file containing basic information on the article such as title, date and tags, everything in here is just MarkDown.
  2. Article information - everything in the <info> section of the article, plus the slug from the filename - has to be added to articles/articles.json.

It then just has to be committed to Git, pushed to the repo on GitHub, and pulled down to the server. Comment files are created automatically when someone leaves a comment, and nothing else needs to be done.

Automating adding articles

I started thinking about alternative ways that I could have articles submitted so that if someone sent me an article, they wouldn't have to add the article to articles.json, and I wouldn't have to add it when they accepted it. This could be done in either of two ways:

I started developing based upon the first point, but I found as I was running git pull origin master in it anyway as it was running on a Git hook, I had all the information I needed. It was far more efficient to just parse the output of that command than to list every file in the directory, which wouldn't have been too efficient as the site got bigger.

I wrote a fairly simple script to run the pull and add the article. At that point, I was only running it through the command line so that I could check the output and make sure that it didn't break anything - I didn't want it running by itself in the middle of the night and breaking the site when I wasn't around to fix it. The plan was that once it was working correctly, I would add it as a service hook on GitHub, so that whenever I pushed to the repository it would send a request to a specific URL on the website, which would run the script. Once I had finished the script, it did three things:

The entire file (build.php, which you can see on the repo) is 69 lines long, most of which is caching the articles.

When I was happy that the file worked as expected, I added the URL as a service hook on GitHub, and tested it with a few articles. It worked!

Other advantages to using GitHub

There is one very obvious advantage to using GitHub: it means that the entire lynx.io website is open source. I'm quite proud of it, so it allows people to see exactly what I have done and how I have done it. This article wouldn't really work if you couldn't see the source! It also forces me to write good code, and allows other people to adapt it for their own websites if they want to (note: if you're going to do this, please change the design!).

The other huge advantage is the pull request system that GitHub offers. Whenever someone wants to submit an article, they just have to add the article file to the articles directory and send a pull request. Previously, they would have had to send me an email, and then I would have had to create them a WordPress account which they would have had to confirm, and then I could have given it permissions to write articles. Then once they had written their article, they would have had to send me yet another email to let me know that they had finished. If there were any mistakes in the article or I had any suggestions, it could have led to a potentially massive amount of emails over multiple days. With GitHub pull requests, I can leave comments inline on the pull request, in the exact place where the errors occur or I think that there could be improvement made.

Inline comments

It also allows me to see the changes, instead of having to reread the entire article like I had to with WordPress.

Diff

Summary

GitHub has completely changed the process of writing for lynx.io. It has made it a lot easier to submit and review articles, and without having to push loads of buttons to add it to the website.

lynx.io: Powered by GitHub!

 

Feel free to submit an article to see how the process works. No article is too short, as long as it is good quality and about website development or design. Check out the README at the root of the repository fo more information.

About Callum Macrae:

Callum Macrae is the founder of lynx.io and a JavaScript developer from the United Kingdom. He is currently writing his first book, to be published by O'Reilly Media.

You can view more articles by this author here.

Tags: lynx.io github deployment

Comments

No comments; leave one below.

says:

Add comment

 

You can use markdown in comments (press "m" for a cheatsheet).

Enable JavaScript to post a comment

Markdown Cheat Sheet

# This is an <h1> tag
## This an <h2> tag
###### This is an <h6> tag

Inline markup: _this text is italic_, **this is bold**, and `code()`.

[Link text](link URL "Optional title")
[Google](http://google.com/ "Google!")

![Alt text](image URL)

![This is a fish](images/fish.jpg)

1. Ordered list item 1
2. Ordered list item 2

* Unordered list item 1
* Unordered list item 2
* Item 2a
* Item 2b

And some code:

// Code is indented by one tab
echo 'Hello world!';

Horizontal rules are done using four or more hyphens:

----

> This is a blockquote

This is an <h1> tag

This an <h2> tag

This is an <h6> tag

Inline markup: this text is italic, this is bold, and code().

Link text Google

This is a fish

  1. Ordered list item 1
  2. Ordered list item 2
  • Unordered list item 1
  • Unordered list item 2
    • Item 2a
    • Item 2b

And some code:

// Code is indented by one tab
echo 'Hello world!';

Horizontal rules are done using four or more hyphens:


This is a blockquote

Toggle MarkDown / HTML (t), full reference or close this