authors_readme.md

Contributing to the Intel Android Hub!

Hello authors! Ready to contribute to a website and skip Wordpress or whatever other CMS people are making you use? We've got a completely open source environment ready for you to write your articles in markdown, jade, or HTML.

   

Setup

1. Fork this repo and then clone your fork. This is to prepare for your future pull request
2. Follow getting started instructions in the main project readme.md to get the basic project running, including running npm install and bower install
3. Follow the rest of these instructions to create yourself as an author and begin writing posts

 

Quick Overview

There's lot o stuff in the project folder, how about I point you to what's relevant for you? =)

androidhub/
└─── data/
    └─── authors/
    		your_github_handle.yaml
    		someone_else.yaml
    		...
└─── posts/
    └─── your_github_handle/
            └─── library/
                image1.png
                ...
    		your-post-file-name.jade
            ...

data/authors/your_github_handle.yaml is a file dedicated to meta data about you, the author. This information is used around the site whenever we're talking about you. posts/your_github_handle/ is your own folder to create your posts in. The child library/ folder is for all your assets (images, etc).

Not too bad right? Tell us about yourself as an author, then go write posts. Bam.

   

Init

If this is your first time contributing to the hub, you'll need to create yourself by putting some data into some files. We've got a handy author kickoff script that does lots of the work for you, so let's start there!

Kick it off!

In your terminal, type npm run new

So what's gonna happen?

All the values you enter into the cli prompt, create a .yaml entry for you in data/authors/, which will look like this. Well, almost like this, it should be filled with information about you.

# Personal Info
displayname:  ''
nickname:     ''
website:      ''
title:        ''

# Social Networks
twitter:      ''
github:       '{{github_handle}}'
codepen:      ''

It also creates a folder for you in posts/{{your_handle}}/ which will hold onto your posts and media. We'll talk about that next.

   

Write

If you're familiar with blog engines like Ghost or Jekyll, then you'll be right at home with the Intel Android Hub's blog architecture. What's awesome about this architecture is you're not limited to just Markdown, you can write Jade, Coffeescript, etc! We felt that most authors would prefer markdown, so that's the style we'll talk about here. Plus, if you know Jade, then you're likely already familiar with it's ability to do markdown.

Kick it off!

In your terminal, type npm run post

Example Post:

---
title:      'My First Post!'
tags:       [android]
categories: [ideate, launch]
heroimage:  ''
excerpt:    'Short description of the article'
---

extends ../views/layouts/_single

block content
  :markdown
    Here's my first post. **How exciting!**

First thing you'll notice is the "front matter." This is yaml style data that get consumed by the architecture and becomes the article meta data. Nothing too strange about the front matter right? It is worth noting, that there is no url front matter key, and that's because the post url will be generated based off the file name of your post. So the pretty url and post title are separate.

But, then we get into some Jade with the extends statement, and if you don't know Jade, check this link for their excellent break down. The main part you'll be working with is what's inside of the block content. This example post is using markdown, and that's simply done by putting any markdown inside of the :markdown Jade filter.

Go markdown crazy. With just markdown alone you can make a very interesting and dynamic article. For the Jade fans or adventurous, you can write your whole post in Jade, include scripts, and basically make your post like you would an HTML page. So in terms of blog post capabilities, this is about as unfettered as it gets!

Images

Drop all of your images into your posts/{your_github_handle}/library/. For your article hero image, just tell us the image name, like android.png. For inline images inside of you post, reference them like /library/{your_github_handle}/file.extension.

Quick Tips

• Recommended size for your hero image is 2000X1338
• You should pick 1 or 2 categories that your article falls under. No more than 3 can be tied to a post.
• Make sure your file names are correctly named and don't include any spaces.
• Run npm test and roots watch prior to submitting a pull request. This will help you catch errors first so your PR passes.

   

Preview

roots watch

Run that awesome command from your terminal, and a live reload web server will fire up and open a tab in your browser. Your post, given it's followed the format and instructions, will appear in the feed. Navigate to it, and you'll have your dev setup ready to go. At this point, we're hoping for a very easy editing scenario for you.

Just to remind ya, every time you save your post, the server will compile and update. Why work any other way right?

   

Tests

npm test

This project is equipped with a test suite to verify and validate your post entries. There are certain required fields, etc, and before you submit your pull request, it would behoove you to run the test suite on your work. This test will be run as a first step by the pull request approver. It's a really easy way to know if you've covered all your bases too.

   

Pull Request

Aw snap, you're ready to push your work to the world. The final step is for you to submit a pull request to the original repo from your fork. Open source is a beautiful thing isn't it? Your pull request will be reviewed and if accepted, will trigger a build in the site. Soon after that, you'll find your work has been deployed to the site, ready for sharing.