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.
To add an article to the website, two things have to be done:
<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.
<info>section of the article, plus the slug from the filename - has to be added to
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.
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:
git pull origin master, seeing if any articles had been added to the articles directory. It could then add the article. Again, this could be ran on either a cron job or a Git hook.
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:
git pull origin master, saving the output to a variable.
create mode \d+ articles\/([a-z0-9_-]+)\.md. That would detect whether any article files had been added in that commit, and save any matches to another variable.
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!
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.
It also allows me to see the changes, instead of having to reread the entire article like I had to with WordPress.
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.
# 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
Inline markup: this text is italic, this is bold, and
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