Getting started
- Clone this repository
- Install Ruby and Jekyll
- Write some Markdown-formatted content and save it as
<file>.md
in theblog/_drafts
folder - Run
jekyll serve --drafts
to have a live preview of the content
Also have a look at the following for more information:
- Formatting content
- Working with drafts
- Are you a new contributor? Add yourself a bio, picture and links to your social sites!
- Using New categories? Add a slug!
Installing Jekyll
Jekyll can be run locally so that we can easily preview how our content is going to look like before it is published.
First, install Ruby if not available in your system.
Second, install the Ruby gems needed by Jekyll
gem install jekyll jekyll-paginate
If on MacOs Catalina (10.15) or higher, the required command is as follows:
xcrun gem install jekyll jekyll-paginate
You may to prefix need sudo to run the command above.
For Windows users, make sure that gem
is in your PATH before running it. For OS X and Linux users, you can run the previous command with sudo
or install the gems locally with
gem install --user-install jekyll jekyll-paginate
If installed locally on OS X or Linux and not already done, you have to update your PATH
to run gem executables directly. The path you have to add to your PATH
variable depends on your Ruby version but looks something like
/Users/$(whoami)/.gem/ruby/2.6.0/bin
Writing content
Add your content to the _drafts
folder for as long as it's not ready to be published. Save it as <file>.md
, do not specify any date while in draft state.
Each must post contain some YAML metadata at the very top:
---
layout: post
title: "Some title"
date: 2015-11-26 08:45:44 +0200
categories: accenture opensource oss lightweight-architecture
---
Testing content
To start Jekyll and see your blog, se the following command:
jekyll serve
Use the following to serve the blog with draft posts:
jekyll serve --drafts
The site will be available at localhost:4000/blog/. Jekyll will regenerate the entire site every time a file is changed, so no need to restart the process after each content change - simply reload the page.
Formatting Content
Content formatting
Jekyll uses Markdown as the formatting language via the kramdown
Ruby library. Please find a quick reference guide here.
Code formatting
In order to have code formatted, use the {% highlight %}
macro:
{% highlight bash %}
echo "Hello, world!"
{% endhighlight %}
Code formatting support is provided by the Pygments library, which supports over 100 languages. Please refer to the documentation for the list of language keys that can be provided to the hightlight macro.
Content Assets
Blog content that uses images to enhance its message is supported and encouraged. In order to add images to a blog post, create a folder under ``ìmg/posts/, preferably using a pattern such as
``` so that it is straightforward to relate image assets to a specific blog post later on.
There are no restrictions to the type and size of image files, but please be conscious about browser support (JPG and PNG are preferred) as well as download size for mobile connections. Assets should be resized and compressed manually at the time of creation of the content, as Jekyll does not support dynamic manipulation of images.
Assets can be referenced from Markdown post content as follows:
![Alt text](/img/posts/<post-slug>/image.jpg)
No need to restart Jekyll when adding new images, as it will automatically detect the new file and copy it accordingly to the right folder.
Article workflow
All new articles must be handled as drafts by placing files in the _drafts
folder.
After authors communicate that content is ready, it will be submitted for proof reading.
Once proof read, the site owner (currently oscar.renalias@accenture.com) will publish the content by moving the draft content to the _posts
folder, and update any missing metadata. Do NOT publish content before it is checked and approved.
Adding new contributors
Each contributor can have his/her own picture, which will be displayed right next to each article authored by the given contributor. Additionally, each contributor can have an own page with a short bio and links to social media profiles.
In order to add a new author:
- edit file
_data/authors.yml
and add a block like the following at the end:
- slug: elizabeth_reed
name: Elizabeth Reed
bio: >
This is a multi-
line
bio
gravatar:
photo: /img/author/elizabeth-reed.jpg
twitter: http://twitter.com/megarameno
facebook: http://facebook.com/megarameno
linkedin: http://linkedin.com/megarameno
Make sure to select a suitable slug, preferably <name>-<surname>
, and fill in social media links accordingly.
-
Add the user's picture to in JPEG or PNG format to folder
img/authors
. Preferably, name it just like the user's slug -
Ensure that the
author
field in the metadata at the top of the post file refers to the author by his/her slug!
Save your changes, let Jekyll recreate the site and verify the results at [http://127.0.0.1:4000/contributors].
Adding new categories
New categories must be defined so that they're visible in the Categories page.
In order to define a new category, add the following block to file _data/categories.yml
:
- slug: lightweightarchitectures
name: Lightweight Architectures