This repository can be cloned and used as a basis for creating a new Eclipse Vert.x how-to. It especially contains the Jekyll and continuous integration configurations for publishing a how-to as a web page.
Each how-to is a self-contained Git repository of the corresponding organisation on GitHub.
The how-to document is written using the Asciidoc text format in a file called README.adoc at the root of the Git repository.
The accompanying source code is directly at the root of the Git repository.
For instance a Maven pom.xml is co-located with README.adoc at the root of the repository.
Projects should preferably have both Maven and Gradle build descriptors. An author who doesn’t have knowledge of either of the tools can always ask for contributions.
A how-to is not a guide or a mini-book: it must be as concise as possible.
In practice this means that each how-to must focus on a very narrow topic. It also means that the text must not deviate from the topic, and that the chosen example must be as simple as possible.
The structure of a how-to must be as follows.
-
Explain the example scenario from a functional point of view.
-
Explain what the user can see when running the example.
-
Highlight the different pieces of code to be written and how they fit together.
-
List all required tools to edit, build and run the how-to.
-
Do not hesitate to point to third-party resources (e.g., if you need Docker, say why you need it and point to its installation documentation).
-
Explain how to create the project.
-
Show the Maven / Gradle build descriptors.
-
For any third-party tool (e.g., running a database with Docker), also have a subsection to explain this.
-
Make one or multiple sections to show the implementation.
-
Make use of Asciidoc source code comments to highlight specific parts of the code.
-
The code must be included using Asciidoc directives. Remember that you can include fragments of code by using delimiter tags.
The website is being rendered using Jekyll and the Asciidoctor extension for Jekyll.
There is a Jekyll theme published as a Ruby Gem, so every how-to uses a common theme.
The common theme depends on the following attributes to be set right below the title header:
= My awesome how-to
:page-permalink: /
:page-github: vertx-howtos/my-howtoThe page-permalink attribute ensures that README.adoc is rendered as index.html rather than README.adoc.
The page-github attribute must contain the joint GitHub organization and repository so it can properly link to the GitHub repository, provide a direct edition link, and more.
The Jekyll configuration shall not have to be tweaked much, here is the basic configuration that we use:
link:_config.yml[role=include]|
Tip
|
When running Jekyll, check the content of the _site/ folder and adapt the exclude items to avoid pushing unnecessary content to the website.
|
You will need Bundler to install all required dependencies:
$ gem install bundler
You can then let Bundler do the installation work:
$ bundle install
From time to time you may also update dependencies:
$ bundle update
The dependencies are specified in the Gemfile file:
link:Gemfile[role=include]|
Tip
|
Keep the vertx-howtos-jekyll-theme dependency up-to-date!
|
The content first needs to be rendered by Jekyll, then the resulting web site files are being pushed to the repository gh-pages branch.
GitHub pages then exposes the content of the gh-pages branch as the website.
While you could do this manually, we automate the process with GitHub Actions.
Pushing to the master branch triggers a deployment, and a daily cron job is in place.
There is a .editorconfig file in this template repository with the 2-space indentation style that we prefer in Vert.x.
In any case, favour readability in samples:
-
do not hesitate to use blank lines,
-
do not over-engineer,
-
use explicit short private methods rather than complicated lambdas expressions.
Asciidoc does not enforce any style.
We recommended that you follow the Asciidoctor recommended practices, and especially the "One sentence per line" rule.