Skip to content

Latest commit

 

History

History
184 lines (133 loc) · 6.31 KB

README.md

File metadata and controls

184 lines (133 loc) · 6.31 KB

3mdeb blog documentation

Table of contents

Deployment status

Production deploy status:

Build Status

Beta deploy status:

Build Status

Usage

Add new post

To add new post to our blog, first prepare local repository:

  1. Clone repository: git clone git@github.com:3mdeb/news-and-ideas.git
  2. Change directory: cd news-and-ideas
  3. Create new file using blog post template
cd blog/content/post
cp YYYY-MM-DD-template-post.md `date +%Y-%m-%d`-my-new-blog-post.md
vim `date +%Y-%m-%d`-my-new-blog-post.md
  1. Familiarize yourself with good practices section.
  2. Use Markdown to write your blog post. You can use local preview
  3. Finished blog post should got to review. Please create Github Pull Request to develop branch as described here
  4. If deployment to beta doesn't show any issues please ask maintainer for sync to master.

Categories and tags

We have several categories you can choose from:

  • Firmware
  • IoT
  • Miscellaneous
  • OS Dev
  • App Dev
  • Security
  • Manufacturing

Basically, there is a huge pool of tags we have, and you can add any tags you like.

Local preview

  1. Remove public directory: rm -rf blog/public
  2. Generate blog: docker run --rm -it -v $PWD/blog:/src -u hugo jguyomard/hugo-builder hugo
  3. Generated files can be found in blog/public

There is possibility to check whether new post is well formatted:

  1. Run local server: docker run --rm -it -v $PWD/blog:/src -p 1313:1313 -u hugo jguyomard/hugo-builder hugo server -w --bind=0.0.0.0
  2. Go to http://localhost:1313/ to view the changes.

Deployment on https://beta.3mdeb.com

  1. Push commits with your blog post to your branch. There are no strict rules for branch naming. It should refer to the post title.

  2. Create a Pull Request, targeting develop branch.

  3. Once your Pull Request gets merged to develop, the blog should be automatically deployed to the beta. You can check the deploy job status on the travis-ci.com

Deployment on production blog

When the blog's status in beta is acceptable, we can deploy to production. To do that, simply create the Pull Request from develop to master. Once it gets merged, the same version of blog should be deployed to production. You can check the deploy job status on the travis-ci.com

Good practices

Grammarly

Grammarly is a great, free tool for all bloggers and anyone who needs to write documentation in English. It will let you know if you skipped a coma or made a typo, as well, as it will check advanced grammar mistakes, too. Bear in mind, that the free version has its limits, so you need to keep an eye on it at all times and still, you are the one who distinguishes when to use a/an or the, as it only suggests changes.

Two versions of Grammarly are available: a plugin for Chrome/Chromium or online application. You need to create an account (it's for free) to be able to use Grammarly.

Visit the website Grammarly and create an account.

It is a MUST-HAVE application for anyone who writes posts or documentation, so feel obliged to use it.

Markdown

There is on the internet a great tool for anyone writing posts, that is Markdown Cheatsheet. It is awesome because it is short and clear.

However, here are some most important commands:

  • #, ##, ###, ####, #####, ###### - headers (just like in HTML <h1><h2><h3> etc.)
  • - some text - it is simply a list item for an unordered list. - <li> in HTML
  • 1. some text - an ordered list. Number does not matter, it will be ordered automatically.
  • [Visible text](URL) - a link
  • ` - inline code. Can be used as an inline quote
  • ` x3 - block of code. You can write, next to it (connected) a programming language

If your post includes any images, they must be located in blog/static/img directory. To link them in file written in Markdown, use the format below:

![alt text](/img/image_name.jpg)

Remember about newlines before markdown tables, lists, quotes (>) and blocks of text (```).

I hope this will help. To see more, visit Markdown Cheatsheet

You can write attach inline HTML into Markdown and it will work! <span style="color: blue">Some text</span>

Single or multiple authors

In general, author meta-field MUST be strictly formatted (lowercase, non-polish letters):

author: name.surname

If post has multiple authors, author meta-field MUST be formatted as below:

author:
    - name.surname
    - name.surname

SEO best known methods

  • Meta description - each post should have single-sentence description with proper keywords (try to add as many keywords as possible)

previously set in the Yoast SEO plugin [TBD - how to set them now]

  • Tags selection - use proper tags (good examples are tags for articles of our competition and results from the Google first site)

  • Graphic/image title - description with keywords related to whole article. All images uploaded to WordPress should be edited in terms of SEO (WP-admin panel in the Media tab). It is required to complete the Caption field and add tags with Meta Tag manager -> Add Meta Tag (at the bottom).