This repository will be used to manage all blog posts published by Ippon USA. All drafting, editing, and peer reviewing will be done through this repository following standard Git best practices.
This README.md
will provide instructions for both a technical audience and a non-technical audience. If you have limited or no git
experience, it is recommended that you follow the "non-technical" section.
- Use GitHub's standard Markdown.
- Start numbering your titles at level 1 (not level 2 like we used to do).
- Don't start a post with a level 1 title, the title indicated in metadata will already be there.
- A paragraph should be a single line of text (no manual wrapping).
- Paragraphs need to be separated by a blank line.
- Avoid abbreviations (e.g. "I've" -> "I have").
- Put your links on the text itself, not after the text it refers to.
Each post should start with metadata. Here is an example:
---
authors:
- Julien Dubois
tags:
- Cassandra
- JHipster
date: 2015-04-23T12:21:50.000Z
title: "10 Tips and tricks for Cassandra"
image:
---
A few notes:
- Authors: you can list one or multiple authors. Authors must exist in Ghost before a post can be sent to Ghost (when a PR is merged).
- Tags: you can list zero, one or more tags. If tags don't exist in Ghost, they are ignored.
- Date: date can be ignored. The real publication date will be overriden from Ghost.
- Title: this should "match" the slug of the post, i.e. the name of the file after converting to lowercase and replacing spaces with dashes.
- Image: an absolute URL to an image file (optional).
- Create a fork of the Ippon USA Blog Repo
- Clone the repo onto your local machine (unless you wish to work directly in the Github UI)
- Create a new file with the
.md
extension in theblog-usa/posts
directory - Write the blog post. Be sure to commit often
- After choosing the graphic that you would like to use in your post, add it to the
blog-usa/images/<year>/<month>
directory - Create link to your image using the format below:
{{< responsive-figure src="link_to_your_graphic" >}}
*** This image may not appear on the "Preview" in Github
Once your post is ready for peer review, be sure to commit any recent updates.
- Push your changes to your forked remote repository
- Submit a pull request from your forked remote repo to the main
blog-usa
repo. Be sure to provide a descriptive title, perferably one similar to your log post title - You are now ready to solicit peer review request for your blog. Provide a link to your pull request to anyone you would like to peer review your blog
Reviewing a blog post will all be done via commenting in the pull request. After receiving a pull request to someones blog post, submit any edits, suggestions, or additions you may have. Be sure to review exisiting comments to prevent duplicates.
- Review suggested changes in the comment section of your pull request
- Make any changes to your blog post either locally (be sure to commit and push) or directly in Github
- Notify the blog administrator that the post is done and ready for publishing
These instruction are targeted towards someone with limited to no experience with Git. This workflow will rely heavily on the Github UI to prevent from having to run git
commands.
Create a Github account if you don't have one already.
- Login to your Github account and go to the Ippon USA Blog Github repository page
- Click on the "Fork" icon in the upper right hand corner. This will create a forked copy of the
blog-usa
repository in your Github remote account - Be sure the title of the repository your currently in is your forked repo NOT the main Ippon USA Blog repo (e.g.
<username>/blog-usa
)
- While in your forked repo, select the
post
directory - Select the "Create new file" button to create a new file with the
.md
extension (e.g.your_blog.md
) - Write the blog post. Use the "Preview" option to get an idea of what your blog will look like when published
- Choose the "Commit directly to
master
branch." option and select the "Commit new file" button - To make any further changes to your post, locate the the file in the
blog-usa/posts
directory. After clicking on your blog post there is a pencil icon on the right hand side. Select this icon to edit your blog. When you have completed your changes and you would like to save (aka commit) scroll to the bottom and "commit new file" directly to themaster
branch
- After choosing the graphic that you would like to use in your post, add it to the
blog-usa/images/<year>/<month>
directory - Create link to your image using the format below:
{{< responsive-figure src="link_to_your_graphic" >}}
*** Note this image will not appear in you the Github preview
- Navigate to the main page of your forked repository
- Select the "New Pull Request" button
- Be sure you are merging to the correct repo and branch. You should be merging your
master
branch in your forked repository to themaster
branch in the main Ipponblog-usa
repo - Select the "Create pull request" button and provide a descriptive title and any neccessay comments. Then select the "Create pull request" button again
- You are now ready to solicit peer reviews. Provide a link to you pull request to anyone you would like to peer review your blog post
Reviewing a blog post will all be done via commenting in the pull request. After receiving a pull request to someones blog post, submit any edits, suggestions, or additions you may have. Be sure to review exisiting comments to prevent duplicates.
- Review suggested changes in the comment section of your pull request
- Make any changes to your blog post directly in Github (be sure to save aka commit)
- Notify the blog administrator that the post is done and ready for publishing