Skip to content

Files

Latest commit

 

History

History
83 lines (59 loc) · 4.99 KB

server-pdfs.adoc

File metadata and controls

83 lines (59 loc) · 4.99 KB

Asciidoctor PDF generation

Server documentation is converted to PDF using the asciidoctor-pdf plugin.

Server Document Structure

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

  • Overview (_server-4-overview.adoc`)

  • Operations Guide (_server-4-ops-guide.adoc)

  • AWS Installation Guide (_server-4-install-guide-aws.adoc)

  • GCP Installation Guide (_server-4-install-guide-gcp.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). There was a breaking change to the way formatting works with the plugin so the latest version that works with the current formatting setup is 1.6.2: https://rubygems.org/gems/asciidoctor-pdf/versions/1.6.2

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

./scripts/build_pdfs_server_4.sh

You will then find the PDFs in: release/tmp

Build PDFs with CI

The CI config for CircleCI docs is configured to build the guides on commit to any branch with /server/ in the title. The PDFs appear as build artifacts and can be accessed from the CircleCI app

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
docs@circleci.com                                                                // 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

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.