How to build and blog on in.relation.to

A bit of Git, a bit of Ruby and you will get your local in.relation.to served.

Table of Contents

Get the source
Set up the build environment — the easy way
Set up the build environment — the hard way
Serve the site locally
Write a blog
Preview changes on staging.in.relation.to
Publish changes to production
Tips & Tricks
License
Acknowledgements

Get the source

> git clone git@github.com:hibernate/in.relation.to.git
> cd in.relation.to

Set up the build environment — the easy way

The easiest way to set up a build environment is to use docker.

See https://github.com/hibernate/awestruct-build-env.

Set up the build environment — the hard way

If you want to run everything directly on your machine without using Docker, first good luck, and then you’ll need to reproduce the environment detailed in https://github.com/hibernate/awestruct-build-env/blob/main/Dockerfile.

Serve the site locally

rake preview

Point your browser to http://localhost:4242. Per default the site is generated with the editor profile enabled. In this profile, posts per tag and author are not generated and only the last 12 months of blog entries are used. The main purpose of this mode is to generate a new blog entry.

If you are developing the blog, you might want to use the development profile. It creates tags and author pages and only considers the last 12 months of blog entries.

rake preview[development]

If you want the full site generated for example to see the full list of tags or authors, you should use:

rake preview[staging]

Write a blog

Blogs are written in Asciidoctor.

Create a file in the directory named after you: for example posts/Emmanuel. The file should be named as followed: yyyy-mm-dd-your-lowercase-dash-separated-slug.adoc. For example 2015-06-30-multitenancy-and-current-session.adoc.

Here is a sample blog template you can start with:

An Asciidoctor blog post

= Let me tell you about...
Emmanuel Bernard
:awestruct-tags: ["Discussions", "Off topic"]
:awestruct-layout: blog-post

Today let's discuss blogging.

== Metadata

You can see that the metadata is made of:

* the title in the first line: it starts with `=`
* the author in the second line: put your first and lastname
* `awestruct-tags`: a list of tags
* `awestruct-layout`: don't change this one

=== Tags

Here is a curated list of tags that you can look at http://in.relation.to/tags/.
Try to use that list, we do not want tag proliferation.
In particular, the general rule is to have tags representing:

* projects, products and podcasts: e.g. `Hibernate ORM`
* specifications: e.g. `CDI` or `Bean Validation`
* a tag representing a release announcement: `Releases`
* a tag representing conferences, JUGs etc: `Events`
* a tag representing discussions: `Discussions`. This one covers development methods, dev tooling, build, etc.
* a tag representing off topic: `Off topic`

== Headers

Sections of a blog post start at level 2 i.e. `==`.
Level 1 is the blog post title.

== Code samples

Code can be highlighted

[source,java]
----
public class Test {
    public String name;
}
----

== More info

You can read more on the Asciidoctor syntax at http://asciidoctor.org.

Happy blogging.

Metadata

You can see that the metadata is made of:

the title in the first line: it starts with =
the author in the second line: put your first and lastname
awestruct-tags: a list of tags
awestruct-layout: don’t change this one

Tags

Here is a curated list of tags that you can look at http://in.relation.to/tags/. Try to use that list, we do not want tag proliferation. In particular, the general rule is to have tags representing:

projects, products and podcasts: e.g. Hibernate ORM
specifications: e.g. CDI or Bean Validation
a tag representing a release announcement: Releases
a tag representing conferences, JUGs etc: Events
a tag representing discussions: Discussions. This one covers development methods, dev tooling, build, etc.
a tag representing off topic: Off topic

Sections

Sections of a blog post start at level 2 i.e. ==. Level 1 is the blog post title.

Code samples

Code can be highlighted

public class Test {
    public String name;
}

More info

You can read more on the Asciidoctor syntax at http://asciidoctor.org.

Happy blogging.

Preview changes on staging.in.relation.to

Use git to push on the staging branch on GitHub. You might need to use "git push --force" to overwrite previous experiments; possibly check when doing so to not interfere with someone else also looking to publish a preview.

Pushing on this branch will trigger a build at the CI Server, if the build is successful your changes should be visible on the staging website.

Publish changes to production

Use git to push on the production branch on GitHub.

In this case, never use "--force" ! If you have a push error, please rebase first, and possibly repeat the staging phase.

Also in this case a build is triggered on the CI Server, and if successful the content is then visible on the public blog.

Note	If you change any of the `.htaccess` files under `server-config`, you need to execute `deploy.sh`. Changes will be applied to the CI server. You need to have access to the CI machine via SSH. Ask you know who. More info in the server-config readme file.

Tips & Tricks

Which other tasks exist in the Rake build file?

> rake -T
> rake -D

The '-T' version will list the available tasks with short description whereas the '-D' version gives the long description.

If your changes are not visible…

Panic! Then completely regenerate the site via:

> rake clean preview

I am getting errors when trying to execute awestruct directly

You need to use bundle exec <command> to make sure you get all required Gems. Check the Rakefile to see how the different awestruct calls are wrapped.

[Linux] Problem with character encodings during execution of awestruct

An error occurred: /in.relation.to/in.relation.to/README.adoc is not valid US-ASCII

Make sure you have the right locale set:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

License

The articles, blog posts and other content of this repository are released under the Creative Commons Attribution Share-Alike 3.0 Unported (CC BY-SA 3.0) license.

All sample code available on these blog posts is released under the Apache Software License 2.0. All source code available in this repository to build the website is also released under the Apache Software License 2.0.

By submitting a "pull request" or otherwise contributing to this repository, you agree to license your contribution under the respective licenses mentioned above.

Acknowledgements

This website uses JBoss Community Bootstrap.

mbellade/in.relation.to

ErrorLooks like something went wrong!

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages