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 run the commands below.
If you’re working on content and want to test the site, the easiest way is:
% ./gradlew prepareJavaScripts
This will fetch JavaScript/CSS dependencies for generating the site. This is needed only once. Then you should run:
% ./gradlew dev
This will start the awestruct dev server, which will be available at http://localhost:4242. This generates each page on the fly the first time you access it, or after you make a change. Compilation will take a second or two, but this is a lot faster than having to generate the entire static site up front.
If you do want to generate the entire site, you can run:
% ./gradlew assemble
|
Note
|
If you run ./gradlew -t assemble this puts Gradle into
continuous
build mode, where it will regenerate the site whenever a .adoc, .haml or
.md file is changed.
|
Once you’ve built the site, the easiest way to test it is with the run task:
% ./gradlew run
This will host the statically generated site at http://localhost:4242, without any automated re-compilation of content.
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.
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:
content/blog/1970/1970-01-01-hello-world.adoc.
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 layout
attribute tells the rendering engine to use the "post" layout.
title will be the displayed title of the post.
tags are descriptive terms for this post.
They can be used to search for all posts for a specific or area,
such as "tutorials" or "plugins".
Tags must contain only numbers and lower-case letters.
Tags must not contain spaces.
Tags should be short, generally one or two words.
Tags containing multiple words should squash all the words together,
as in "continuousdelivery" or "jenkinsworld2017".
Dashes are allowed but should be avoided unless describing a topic that contains dashes,
such as a plugin name that contains dashes.
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
file named 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!
---Only the name: and 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.
|
Tip
|
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!Becomes:
|
Note
|
This is a notice that you should pay attention to! |
|
Caution
|
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.
The different chapters for the Handbook are located in the content/doc/book/ directory
and generally speaking each .adoc file represents a single chapter of the book.
Chapters are automatically surfaced on the Handbook home page (provided by
content/doc/book.html.haml).
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 .adoc
file for the Getting Started Guide, as well as any supplementary images or other
assets to accompany
the guide.
|
Tip
|
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. |
Solution pages are somewhat special insofar that they are not generally AsciiDoc files,
but rather Haml templates. All the solution pages are located
in the content/solutions/ directory hierarchy, with some data provided for the solution
pages in content/_data/solutions/.
|
Important
|
The naming of Solution page template (pipeline.html.haml) must
match the data file in content/_data/solutions, e.g. pipeline.yml
|
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.
Encouraged formats:
-
Asciidoctor (basic content creation) (AsciiDoc syntax quick reference)
-
Haml (more advanced/custom page) (Haml syntax reference
Adding a new page is as easy as adding a a new file to the content/
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
filename.
The content/index.html.haml page is one such example of a special-case,
standalone page.
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 content/my-clean-url/index.adoc.
(Advanced Haml users would create content/my-clean-url/index.html.haml).
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).
The awestruct gem provides a command line interface which is very useful. If
you’re using MRI (aka "CRuby", non-JRuby), just
execute: ./gradlew dev and you’ll have a live-reloading webserver running
on localhost:4242
In order to get a legacy version of jenkinsci.org, ./gradlew dev-legacy
There is rudimentary (as in if it doesn’t work, you’re on your own) support for publishing the static site to GitHub Pages for demonstration purposes using the Awestruct Deployer.
This requires adding a
profile
to content/_config/site.yml for your fork, and manually operating
awestruct