active | layout | date | permalink | title | description | file | tags | author |
---|---|---|---|---|---|---|---|---|
contribute |
article |
2021-05-18 10:22:58 +0530 |
/contribute/ |
Contribute to Ruby News |
Learn how to Contribute to Ruby News |
contribute |
RubyNews Contribute |
Ruby News |
Ruby News is a website where we weekly tips, tricks and guides about the Ruby programming language!
Not only this site is open source, but anyone can contribute to Ruby News!
Here in this guide, we are going to take a look at how we can contribute articles to Ruby News.
Section |
---|
File formats |
Uploading a new Post and Link - Front Matter Guide |
Uploading Images |
Markdown Cheatsheet |
Markdown with Specific HTML Tags |
Uploading Article to Codebase |
An article can be either in **HTML** or **Markdown** format
HTML formatting can be easy but it can consume a lot of time because all the tags
- HTML files have .html extension.
- HTML documents have opening and closing tags, and sometimes empty tags
- HTML documents can be long compared to markdown
We recommend using markdown because:
- Markdown files can have either .md or .markdown extension.
- It's simple enough hence faster to write an article in markdown.
- It doesn't need any opening and closing tag.
- Uniform styles are automatically fetched from our codebase.
To write a new post:
- Move to the _posts directory
- Create a markdown file with the YYYY-MM-DD-article-title.md format. Some examples:
2021-05-18-my-first-article.md
2021-05-18-hello-world.md
2021-05-18-this-is-another-article.md
-
The file should have a front-matter - front-matters are simple YAML code that determines the post title, date, description, the preview image, etc.
All files should start with these lines of code:
---
layout: article
title: "How to Make Ruby Fast with GCC Optimization"
description: "Make Ruby Fast with GCC Optimization"
file: "gcc-optimization"
# link: https://...
preview_image: "main.jpg"
tags: Ruby Optimization GCC
author: 'Ruby News'
###########################################
#
# Allows you to control behaviour on the index page cards
# > Background shown on the index page as a list, default: true
# > Blurring is only shown when full_background is set to false
# and the image don't fit the card. This is helpful for
# preview images with transparent background
# default: true
preview_full_background: false
preview_blur: true
# Allows you to control behaviour on the article page
# > Background shown on index page as a list
# > Blurring is only shown when full_background is set to false,
# and the image doesn't fit the grid
# article_full_background: false
# > round_borders allows you to round the border of the home image,
# defualts to false
article_preview_blur: true
round_borders: false
---
Right, the code is wrapped inside ---
.
- layout: The
layout
line determines the layout - it's alwaysarticle
- title: The
title
mentions the title of the post. This defaults to the post title, if not provided. - description: Description describes the articles in few words. The default is the post title if not provided.
- file: The file name! It's the filename without the date. For example,
If your file name is
2021-05-18-hello-world.md
, then your file name ishello-world
If it's not a file, then it could be a hyperlink! In that case, clicking on the link will take you to another page in a new browser tab. - preview_image: This field determine the image to be shown in the index page! We will soon see where to upload images and assets.
- tags:
tags
helps you to better categorize your post! - author: This field determines the author name. It could be your name.
preview_full_background: false
preview_blur: true
article_full_background: true
article_preview_blur: true
round_borders: false
These fields determine the image styling done on the index page and in your post! These fields have a default value, and you may or may not include them.
To upload links only:
- Create a
.md
file inside _posts directory, with the formatyyyy-mm-dd-post-name.md
- Create an image directory inside posts_images/yyyy-mm-dd, with the same year, month and date, unless the folder already exists.
Put the contents:
---
active: "articles"
layout: article
link: https://some-website.net
tags: Testing
preview_image: "main.jpg"
author: 'Author Name'
# Background shown on index page as list
# preview_full_background: false
# preview_blur: true
---
As a regular article, the preview_image will get automatically fetched from posts_images/yyyy-mm-dd/main.jpg
.
Clicking on the link will take the user to the link in a new browser tab.
Images are very easy to mess up, and it's hard to track which image belongs to which article - if we have tonnes of unneeded images, we can't find them.
To prevent this situation, we have a very specific way to upload images. Nevertheless, uploading an image is simple, you need to keep these points in mind:
- Go inside post_images
- Create a new directory as the date of your post. For example:
2021-05-18
- Upload your images
- To set the preview image, upload the image, and then in the post set preview_image: "main.jpg"
The articles that you upload should be a markdown, markdown files end with .md or .markdown extension.
Here's a cheatsheet of markdown from markdownguide.org
Element | Markdown Syntax |
---|---|
Heading | # H1<br> ## H2<br> ### H3 |
Bold | **bold text** |
Italic | *italicized text* |
Blockquote | > blockquote |
Ordered List | 1. First item 2. Second item 3. Third item |
Unordered List | - First item - Second item - Third item |
Code | `code` |
Horizontal Rule | --- |
Link | [title](https://www.example.com) |
Image | ![alt text](image.jpg) |
Element | Markdown Syntax |
---|---|
Table |
| Syntax | Description | |
Fenced Code Block | ``` |
Footnote |
Here's a sentence with a footnote. [^1] |
<grid-2>
<div>Column 1</div>
<div>Column 2</div>
</grid-2>
You can specifically get grid-2, grid-3 to grid-9, the last one adds 9 grids for example. This way, you can add text beside images.
Other tags include
with dollar ($) or hash (#) sign, which is not user-selectable while copying codes:<pre><dollar>echo "hello world!"</dollar></pre> <pre> <hash>whoami</hash> Root </pre>
echo "hello world!"whoami RootYou can also add file names with pre tags:
<pre> <file>app/javascript/packs/application.js</file> require("@rails/ujs").start() require("turbolinks").start() require("channels") require('jquery') require('bootstrap') import Rails from '@rails/ujs' </pre>
app/javascript/packs/application.js require("@rails/ujs").start() require("turbolinks").start() require("channels") require('jquery') require('bootstrap') import Rails from '@rails/ujs'Remember to add html tags inside html tags.
That's it! That's what we have for HTML specific tags.
If you want to add line breaks or you need some specific HTML tags, feel free to use them.
Make sure to close tags properly when required.
After you wrote an article, you need to push it to the codebase. For pushing an article to the codebase:
-
You can fork the project, and write some articles there:
- All the articles go to
_posts/
directory - All the images goes to
_images/yyyy-mm-dd/
directory, where the yyyy is your post year, mm is the month and dd is the date.
- All the articles go to
-
If your git skill is a bit rusty, feel free to drag-drop articles to your forked copy of this repo. And send us a Pull Request.
-
You will be an author of that article once your contribution is merged by the moderators.
-
You don't have to worry about SEO and search features, everything is just automatic :)