Contributing to the Jenkins website
Mac OS X pre-requisites
Ensure you have the latest python and ruby installed using Homebrew.
% brew install python ruby
This project uses Gradle to build, so as long as you have JDK7 or later in your path, you should be able to build the site with:
% ./gradlew assemble
If you run
The easiest way to run the site is with the run task:
% ./gradlew run
This will host the statically generated site at http://localhost:4242
The majority of what is considered "legacy" content is almost entirely under
content/blog. These files represent structured around the date the original
stories were written in Drupal.
Adding a blog post
In order to add a new blog post, create a new file ending in .adoc (for
Asciidoctor) in the appropriate
content/blog/<year> directory with the full date and a lower-case title for
your post. In effect, if you’re writing a post that you want to title "Hello
World" on January 1st, 1970, you would create the file:
In that file you need to enter some meta-data in the following format:
--- layout: post title: "Hello World!" tags: - jenkins - timetravel author: yourgithubname ---
This section is referred to as the
front matter. The
attribute tells the rendering engine to use the "post" layout,
tags should be fairly self-explanitory. The "author" attribute will map your
GitHub name to author information, if this is your first time adding a blog
post, please also create an "author" file in
content/_data/authors/ with the
yourgithubname.adoc. The format of this file should be:
--- name: "Your Display Name" twitter: meontwitter github: yourgithubname --- This is an *AsciiDoc* formatted bio, but it is completely optional! ---
github: sections are mandatory.
Once your author file is defined, you can return to your blog post file
1970-01-01-hello-world.adoc), finish creating the "front matter" and then
write your blog post!
Once you have everything ready, you may create a pull request containing your additions.
|If you’re unfamiliar with the AsciiDoc syntax, please consult this handy quick reference guide.|
This repository holds the central documentation for the Jenkins project. The documentation can be broken down into three categories:
Knowledge-base/Handbook - rich and in-depth documentation, separated into chapters covering a topic area, conceptually similar to the FreeBSD Handbook
Getting Started guides - topic-specific, progressive documentation walking the reader through the topic
Solution pages - topic-specific destination pages providing a high-level overview of a topic with links into getting started guides, handbook chapters, relevant plugins and multimedia related to the topic
Generally speaking, all documentation should be written in AsciiDoc. While most open source contributors are familiar with Markdown it has limitations which make writing in-depth documentation with it problematic.Markdown, as opposed to GitHub flavored Markdown, does not have support for denoting what language source code might be written in. AsciiDoc supports this natively with the "source code" block:
[source, asciidoc] \---- This is where I would _cite_ some highlighted AsciiDoc code \----
AsciiDoc has a number of other features which can make authoring of documentation easier, such as the "admonition blocks" which help call out specific sections, such as:
NOTE: This is a notice that you should pay attention to! CAUTION: This is a common mistake!
|This is a notice that you should pay attention to!|
|This is a common mistake!|
There are too many other helpful macros and formatting options to list here, so it is recommended that you refer to the quick reference to become more familiar with what is available.
Adding a Handbook chapter
The different chapters for the Handbook are located in the
and generally speaking each
.adoc file represents a single chapter of the book.
Chapters are automatically surfaced on the Handbook home page (provided by
Adding a Getting Started Guide
Unlike Handbook chapters, Getting Started Guides should be directed, that is to say: the sentence "Getting Started with X" should make sense. "Getting Started with Jenkins on Windows", "Getting Started with Pipeline", "Getting Started with Access Control".
These getting started guides can be placed in
content/doc/ in a directory that
is most appropriate for the topic, and the directory should contain the
file for the Getting Started Guide, as well as any supplementary images or other
assets to accompany
|Writing a Getting Started Guide while authoring a Handbook chapter on the subject can help ensure your Getting Started Guide can cite more detailed documentation for how/why certain features exist, or provide a useful reference point for "advanced" features.|
Adding a Solution page
Solution pages are somewhat special insofar that they are not generally AsciiDoc files,
but rather Haml templates. All the solution pages are located
content/solutions/ directory hierarchy, with some data provided for the solution
The naming of Solution page template (
New solution pages should help guide a reader to documentation and resources about a very specific topic, or use-case, on Jenkins. How specific/niche the solution pages should be requires a bit of judgement, for example "Jenkins for Visual C" is probably too niche to fill out a page with a rich set of plugins, presentations and links to documentation. A page "Jenkins for C/C" would still be relatively specific, and could easily include a section for Visual C++/Windows specific content.
Adding a stand-alone page
Adding a new page is as easy as adding a a new file to the
directory. It is important to keep in mind that the filename you choose will
be the URL of your page, so ensure you have a lower-case and useful
content/index.html.haml page is one such example of a special-case,
In order to have a clean URL, e.g. "https://jenkins.io/my-clean-url", you would
need to create a directory with your content in it. Using the above example, I
would create the directory
content/my-clean-url and if I were creating an
Asciidoc file, I would then create the file
(Advanced Haml users would create
The underlying technology is awestruct which is Ruby project, but to make it easy to use we’ve wrapped these Ruby scripts with JRuby/Gradle. If you wish to circumvent using Gradle entirely, you can do so, so long as you manage your own Ruby development environment (e.g. with RVM).
bundler gem and then run
The awestruct gem provides a command line interface which is very useful. If
you’re using MRI (aka "CRuby", non-JRuby), just
./gradlew dev and you’ll have a live-reloading webserver running
In order to get a legacy version of jenkinsci.org,