Handbook

Blogs

Formatting and Review

Good formatting improves readability, and a careful review pass catches issues before the post reaches readers.

Formatting

References and Formatting

Provide External References

Always include links when referencing external information.

Helpful references include:

  • Official documentation
  • Pull requests
  • Social media or event references

Adding Images

Images should be stored in the images folder.

Use the following syntax to insert images:

{% include post_image.html file="image_name.png" description="Image description" %}

Use images when:

  • Demonstrating UI features
  • Showing configuration steps
  • Explaining workflows

Images should always include meaningful descriptions.

Highlighting Code

Use syntax highlighting for code blocks.

{% highlight yml %}

Rails.application.secrets.mailer_default_from_email

Rails.application.secrets.support_email

Rails.application.secrets.mailer.smtp_settings

{% endhighlight %}

Replace the language identifier with the appropriate language such as ruby, javascript, bash, sql, or text.

Code Formatting Guidelines

  • Add line breaks before and after code blocks.
  • Add spaces around operators.
  • Prefer clean, readable formatting in every snippet.

Example

Incorrect: a+b

Correct: a + b

Adding Quotes

Quotes can be added using:

Rails emphasizes convention over configuration.

Review

Review Before Submitting

Use Grammar Checking Tools

Before submitting a blog post, run grammar checks using tools such as:

  • Grammarly
  • LanguageTool
  • Built-in editor spell check

These tools help detect spelling mistakes, grammar errors, and punctuation issues.

Preview Before Submitting

If the blog includes images, run the blog locally before submitting the pull request.

This ensures:

  • Images are compressed properly
  • The blog builds successfully
  • Layout issues are detected early

This step helps reduce build time and improve page load performance.