- Create an issue for your blog post in this repository.
- Fork this repository and clone. Note that you're working off of the default
prod
branch. - Creating/Updating blog content:
- For a new blog post, create a new file in the posts directory with the name in the format
YYYY-MM-DD-post-title.adoc
where the date represents the expected publication date (e.g.2021-11-21-open-liberty-is-awesome.adoc
) and write your post.- Update the blogs_tags.json by adding your blog post to the start of the
posts
array (1-2 entries per line) for each appropriate tag.
- Update the blogs_tags.json by adding your blog post to the start of the
- For an existing, published blog post, simply make the change to the existing blog post file in the posts directory.
- If necessary, update the blogs_tags.json by adding/removing the blog from the
posts
arrays (add to beginning, 1-2 entries per line) of the tags.
- If necessary, update the blogs_tags.json by adding/removing the blog from the
- For an existing blog post that has not been published, you'll need to either cherry pick the commits from the
draft
branch, or work off of the branch/fork that was used to deliver those commits.- If necessary, update the blogs_tags.json by adding/removing the blog from the
posts
arrays (add to beginning, 1-2 entries per line) of the tags.
- If necessary, update the blogs_tags.json by adding/removing the blog from the
- Any images that you want to reference in your blog post must be placed in img/blog directory.
- For more information regarding creating/editing blog post content (like multiple authors, third-party posts, etc), refer to documentation that follows this section.
- For a new blog post, create a new file in the posts directory with the name in the format
- Once finished and verified locally (adoc editor or blog docker image) create a pull request into the
draft
branch (linked to the issue you created in Step 1) with @lauracowen or anyone else as reviewer, and merge upon approval. - Request a build of the draft site:
- Go to Travis CI
- More Options > Trigger Build > Make sure the
master
branch is selected (default) > Trigger custom build
- Once the build completes, check to make sure the blog renders correctly on the draft site and resolve any problems (like formatting/styling). Resolve the issue first in the personal branch and create another PR into
draft
branch and repeat steps 4, 5, & 6 until all issues are resolved. - Once everything is [BROZ]
- Create a PR from your
personal branch
intostaging
branch renaming the file to match today's dateYYYY-MM-DD-post-title.adoc
, provide a link to your post on the draft site and add @lauracowen, SMEs, and/or other reviewers to get their final approval for both content and format. To make any changes, update the PR with new commit and repeat step 5 & 6 until all issues are resolved. Once approved, @lauracowen (or another admin) will merge the PR intostaging
and shepherd the post through the remaining steps. - Request a build of the staging site (same as step 5)
- Go to Travis CI
- More Options > Trigger Build > Make sure the
master
branch is selected (default) > Trigger custom build
- Once the build completes, check to make sure the blog renders correctly on the staging site. This is the final check before the post goes into the production site.
- If there are issues found on the staging site, they must be resolved quickly, either by merging a new PR with a fix, or reverting it. If you pushed a new PR with the fix, make sure it also gets pushed to the
draft
branch. - Create a PR from
staging
branch intoprod
branch an admin approver. Once approved, merge intoprod
. - Rebuild the production site on IBM Cloud and verify the post looks as expected on openliberty.io
Summary of commit flow through branches:
prod
<-PR- staging
<-PR- draft
<-PR- personal branch from fork
In other words, prod
should always be a commit subset of staging
which should be a commit subset of draft
. Note, however, that you're not actually, normally, doing a PR from draft
to staging
but instead from your personal branch from fork
into staging
, but only after it already has been in draft
.
Blogs are written in AsciiDoc format with a file extension of .adoc
.
In the blog post file the following front matter variables must be set:
- layout: post
- title:
title of the blog post
- categories: blog
- author_picture:
secure url to author picture
- If a picture cannot be found, the openliberty.io logo can be used instead https://avatars3.githubusercontent.com/u/28316667
- author_github:
secure url to author github
- blog_description:
Description of blog post used in the preview card on openliberty.io/blog
- Please keep your
blog_description
to around 60 words
- Please keep your
- seo-title:
Blog Title used in search results and on social media - OpenLiberty.io
- Please ensure that your
seo-title
ends with- OpenLiberty.io
- Please ensure that your
- seo-description:
Blog Description used in search results and on social media
- Please keep your
seo-description
between 50-300 characters
- Please keep your
If you would like to publish a blog post with more than 1 author, you can add the additional_authors
attribute to the liquid front matter. Any number of additional authors can be specified using the following format:
additional_authors:
- name: author 2 first and last name
github: secure url to author 2 github
image: secure url to author 2 picture
- name: author 3 first and last name
github: secure url to author 3 github
image: secure url to author 3 picture
If you would like to add a blog post that is actually a link to an existing third party blog post, you can follow the normal steps described above for creating a blog post. You simply need to add the following attributes to the liquid front matter:
- redirect_link: secure_url_to_3rd_party_post
- permalink: /blog/redirected.html
Also provide a level 1 heading eg:
= Creating a cool app with MicroProfile
Certain characters (eg apostrophe ' ) in the main heading are displayed incorrectly. To fix, escape with a backslash (\
).
eg = Minimise turnaround times with Open Liberty\'s dev mode
Github.com does a pretty good job of rendering asciidoc so you can preview your file there, but to see exactly what it will look like you'll need to install the website software and run it.
git clone https://github.com/OpenLiberty/blogs.git
git clone https://github.com/OpenLiberty/openliberty.io.git
docker pull kinueng/openliberty.io
Replace "currentFolder" in the following command with the full path to the folder you are in.
docker run --rm --name website -it -p 4000:4000 -v currentFolder/openliberty.io:/home/jekyll kinueng/openliberty.io
# example when current directory is /Users/bruce/projects/blog/website:
# docker run --name website -it -p 4000:4000 -v /Users/bruce/projects/blog/website/openliberty.io:/home/jekyll kinueng/openliberty.io
Before your new or updated blog entry will appear on the website, you will need to run the script below to update the container with your latest changes, then wait for the container to finish processing them. Then you can see your changes at http://localhost:4000/blog/
Note that blogs named with dates in the future, e.g. 2099-01-05, will not be shown, so don't do that.
./blogs/scripts/refresh_docker_image.sh
You will see Jekyll
detect your new files and regenerate the blog files. You will want to wait for the line "...done in XXXX seconds."
Regenerating: 101 file(s) changed at 2018-10-29 18:53:10
...
Jekyll Feed: Generating feed for posts
...
...done in 121.8705398 seconds.