Giters

vladmihalcea / in.relation.to

Awestruct version of in.relation.to

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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

Prerequisites

Installation

Ensure Rake is installed

Make sure Rake is available. It is often installed per default.

> rake --version

If you get "command not found":

> gem install rake

Ensure Bundler is installed

Make sure Bundler (version >= 1.10) is available. It manages your Ruby gems locally to the project and prevents version conflicts between different Ruby projects. Quoting from the website:

Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.

> bundle -v

If you get "command not found" or a version < 1.10:

> gem install bundler

Get the source

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

Setup awestruct

> rake setup

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.

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.

Fedora 22 setup

Make sure the user is in the sudo group and install required dependencies for compilation of native extensions:

> sudo dnf -y install gcc-c++ make ruby-devel libxml2-devel libxslt-devel
Note

This is required regardless how you proceed from here (provided Ruby version ns RVM)

Using Ruby version provided by the Fedora packages

> sudo dnf -y install ruby
> gem install rake bundler

Continue here

Using RVM

How to Integrating RVM with gnome-terminal: http://rvm.io/integration/gnome-terminal

How to install RVM (http://rvm.io/rvm/install)

Install the GPG key:

gpg2 --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3

Install a stable Ruby version:

curl -sSL https://get.rvm.io | bash -s stable --ruby
git clone in.relation.to
cd in.relation.to
echo "rvm ruby-2.2@global” > .rvmrc

Load the .rvmrc file:

cd ../in.relation.to

Say yes to .rvmrc execution.

Continue here

Bugger that,…​

I cannot get the enviroment up and running. Use Docker! Read how!

[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.

About

Awestruct version of in.relation.to

Languages

Language:HTML 95.8%Language:JavaScript 1.9%Language:Ruby 1.8%Language:CSS 0.4%Language:Dockerfile 0.0%Language:Shell 0.0%