Skip to content

Latest commit

 

History

History
158 lines (115 loc) · 7.06 KB

server-docs.adoc

File metadata and controls

158 lines (115 loc) · 7.06 KB

CircleCI Server Documentation

Server documentation is written in ASCIIDOC and built for the web and PDF using jekyll-asciidoc and asciidoctor-pdf plugins.

Document Structure

Server documentation is provided in two formats:

  • HTML on the main CircleCI docs site showing the current docs for server 2.x

  • PDFs of our Operations and Installation guides are provided for each feature release (scroll down to the bottom of the Server Administration section in the main navigation)

Each topic/guide is written in a separate .adoc file, and for the purposes of PDF generation there are master .adoc files for:

  • Operations Guide (_ops-guide.adoc)

  • Installation Guide (_aws-install.adoc)

These "master files" combine the separate topics using the include::jekyll/_cci2/overview.adoc[] etc. syntax.

Note
 Master asciidoc files that are only used for creating PDFs have an _ at the start of the filenames to prevent Jekyll from converting them to HTML for the main site.

Build PDFs locally

To be able to build PDFs locally you will need to install Asciidoctor-PDF - Instructions [here](https://github.com/asciidoctor/asciidoctor-pdf#install-the-published-gem).

Then, from the top of the circleci-docs directory, run:

./scripts/build_pdfs_asciidoc.sh

You will then find the PDFs in: releases/tmp

Build PDFs with CI

The CI config for CircleCI docs is configured to build the Operator and Installation guides on commit to any branch that starts with server/*. The PDFs appear as build artifacts and can be accessed from the CircleCI App

Some Notes on Formatting in Asciidoc

See the Asciidoctor user manual for all available features: https://asciidoctor.org/docs/user-manual/.

In the next few sections, note some of the main formatting differences to markdown:

Using code blocks in numbered steps

To generate numbered steps (an ordered list) use the following syntax:

. step 1 text
. step 2 test
. step 3 text

To keep numbered steps flowing correctly when code blocks, images or admonitions are used inside steps, use the + on the line before the block starts to indicate the block is part of the step above:

. Step one
. Step two involves some code
+
[source, shell]
----
some code
----
. Step three is still in number order

Style tables correctly for the Jekyll site

To display tables correctly in the web version of Server docs, assign them with the .table and .table-striped classes and use the following table syntax:

[.table.table-striped]
[cols=3*, options="header", stripes=even]
|===
|column 1
|column 2
|column 3

|column 1 row 1
|column 2 row 1
|column 3 row 1

|column 1 row 2
|column 2 row 2
|column 3 row 2
|===

Inter-document cross refs

Cross references should be made in the form:

<<overview#services-machine,Services Machine>>

  • overview is the name of the file the destination is in

  • services-machine is the anchor heading for the section you are linking to (this can also be left blank)

  • Services Machine is what to display in the prose

This process is a little trickier when cross referencing between the install and ops guides as the xref needs to work for the PDF, across two separate docs, as well as the Jekyll site where you will be dealing with two regular pages as with any xref. In this instance, reference the URL of the Jekyll version, so instead of using the <<>> described above, use a normal asciidoc link, for example:

https://circleci.com/[The CircleCI Website]

Document Attributes

Each individual doc should begin like this:

= Overview                  // top level heading
:page-layout: classic-docs  // page layout to use
:page-liquid:               // apply Liquid template preprocessor to file prior to content being passed to AsciiDoc processor
:icons: font                // use font awesome icons for admonitions
:toc: macro                 // allows you to place the TOC wherever you like in the doc using toc::[]
:toc-title:                 // gives the option to customise the TOC heading

Attributes for Master Docs

= OPERATIONS GUIDE: A guide for administrators of CircleCI Server installations. // main title
[email protected]                                                                // author
:media: screen                                                                   // destination media type
:title-page-background-image: image:pdf-header.png[]                             // image overlay for front page
:imagesdir: ../assets/img/docs/                                                  // where to find images included in content
:doctype: book                                                                   // https://asciidoctor.org/docs/user-manual/#document-types
:toc:                                                                            // default places TOC right after front page
:toc-title: Contents                                                             // heading to appear above TOC
:icons: font                                                                     // use font awesome icons for admonitions
:source-highlighter: rouge                                                       // use rouge syntax highlighter for PDF output
:pagenums:                                                                       // print page numbers in PDF output
:idprefix:                                                                       // by default IDs generated from section titles start with _ ... this removes it
:idseparator: -                                                                  // use - between words for IDs generated from section titles
:autofit-option:                                                                 // auto-fit code blocks to the page width

Prevent Heading from Appearing in TOC

[discrete]
== Heading

Liquid Tags and Other Content You Do Not Want in the PDFs

Liquid, used for the Jekyll content, is not rendered during the PDF conversion process. If {% raw %} tags are used in Server docs pages they need to be removed from the PDF content, so that they do not appear as text in the PDF. This can be done using the ifndef directive, as follows:

ifndef::pdf[{% raw %}]
code example
ifndef::pdf[{% endraw %}]

Highlight Content (useful for to do items so they don’t get missed and published!)

To highlight some text in the html/pdf output just enclose it in #, as follows, leaving no gaps:

#text to highlight#

The script that builds the PDFs applies an attribute called pdf during the build - so any content that uses ifndef::pdf will not be included in the generated PDFs. For further information on usage and the inverse ifdef::pdf see the Conditional Preprocessor Directives section of the Asciidoctor user manual. This same process can be used to create any type of content to appear on just one of our platforms.