Ensure you have GNU/Make and Docker available on your machine:
-
make --version -
docker version
Docker must be version 17.04 or greater.
This project uses GNU/Make and Docker in order to generate the fully statically generated jenkins.io web site. The key tool for converting source code into the site is the Awestruct static site generator.
-
make prepare will download external dependencies and files necessary to build the site. It is recommended that this be executed at least once before authoring new content. This target is not a dependency of
runorgenerateas an optimization to make iterating on content locally more pleasant. -
make run will run a live-reloading development server on localhost:4242
-
make pdfs will explicitly generate new PDFs
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>/<month> 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/01/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).
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