Welcome to Ruby News Contribution Guide!
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.
Writing Article Guide
|Downloading the repository|
|Uploading a new Post and Link - Front Matter Guide|
|Markdown with Specific HTML Tags|
|Uploading Article to Codebase|
Downloading The Repository
To create a new post:
- Visit the project repository page.
- Clone the repository to your local machine.
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.
Uploading a new Post and Link - Front Matter Guide
We would prefer markdown files for article creation.
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_link: "image link" tags: Ruby Optimization GCC author: 'Ruby News' #Show preview image on article? If you have another image to insert, set this flag to false show_preview_image_on_article: false ########################################### # # 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
Let’s take a look at the mandatory fields:
- layout: The
layoutline determines the layout - it’s always
- title: The
titlementions 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 is
hello-worldIf 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_link: This field determine the image to be shown in the index page!
tagshelps you to better categorize your post!
- author: This field determines the author name. It could be your name.
Let’s take a look at the non-mandatory fields:
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.
Uploading only links:
To upload links only: create a
.md file inside _posts directory with the format
Put the contents:
--- active: "articles" layout: article link: https://some-website.net tags: Testing preview_image_link: "image link" author: 'Author Name' # Background shown on index page as list # preview_full_background: false # preview_blur: true ---
Clicking on the link will take the user to the link in a new browser tab.
To upload an image you need to provide a link to the image.
If the image is stored on Google Drive, follow the steps below:
- Copy the ID from the original URL (the characters between the /d/ and /view)
- Add your id to ‘https://drive.google.com/uc?export=view&id=’
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
|Ordered List||1. First item
2. Second item
3. Third item
|Unordered List||- First item
- Second item
- Third item
|Fenced Code Block||
Markdown with Specific HTML Tags
But you can also integrate HTML into markdown! If you want to align an image with text, you can add this:
<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 <pre> 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!"
You can also add file names with pre tags:
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.
Uploading Article to Codebase
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.
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 :)