A bit of Git, a bit of Ruby and you will get your local in.relation.to served.
Set up the build environment — the easy way
The easiest way to set up a build environment is to use docker.
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:
= 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
orBean 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
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.
If you change any of the 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
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.