Repository files navigation

Note: Bookbinder and this GitHub repository are no longer supported.

This is the repository for 'bookbinder' and 'bookbindery' gems. On 2015/01/07 the 'bookbinder' gem was renamed to 'bookbindery' gem.

To use the Bookbindery gem, include the following in your book's Gemfile:

source 'https://rubygems.org'gem 'bookbindery'

Bookbinder is a gem that binds together a unified documentation web applicationfrom disparate source material.Source material can be in markdown, HTML, orDITA, and must be stored in local directories orin git repositories.Bookbinder runsmiddleman to produce a Rack appthat you can deploy to Cloud Foundry.

See theBookbinder wiki for detailed information and instructions, such as how to configurecredentials for multiple git services.

Note: Bookbinder has been tested on the following Ruby versions:

• 2.5.3
• 2.5.5
• 2.6.3
• 2.6.6
• 2.6.8

Follow the instructions below to install Bookbinder:

1. Addgem "bookbindery" to your Gemfile.

2. Runbundle install to install the dependencies specified in your Gemfile.

3. (Optional) Install theDITA Open Toolkit(DITA-OT).

   Bookbinder uses theDITA Open Toolkit (DITA-OT)to process documents written in DITA.If you have DITA sections in your book, you must install DITA-OT to processthem.

   Once installed, specify the location of the DITA-OT library as anenvironment variable namedPATH_TO_DITA_OT_LIBRARY.

   We recommend that you use thefull_easy_install type for the DITA-OTlibrary.

   Note: Ensure that the version of the DITA-OT library that you installsupports the DITA version in which your documents are written.

1. Install Ruby and needed dependencies

   gem install bundlerbrew install ant

2. Install Dita-OT, version 1.7.5, full easy fromhttp://www.dita-ot.org/download

   cat >> ~/.bash_profile << EOFexport PATH_TO_DITA_OT_LIBRARY="/Users/pivotal/workspace/DITA-OT1.7.5"EOFexport PATH_TO_DITA_OT_LIBRARY="/Users/pivotal/workspace/DITA-OT1.7.5"

3. Build the book and view it

   bundle exec bookbinder bind localcd final_app/rackup

Bookbinder is intended to be used from within a project called abook.The book includes a configuration file. theconfig.yml, that describes which documentation repositories to use assource materials.

Thebookbindery gem provides a set of scripts to aggregate those repositoriesand publish them to various locations.

Bookbinder also provides scripts for running on a Continuous Integration system that can detect when a documentationrepository has been updated with newcontent, and that can verify a composed book is free of any dead links.

1. To create a new book on your local machine, runbookbinder generate BOOKNAME, replacing BOOKNAME with the name of your book. For example:

   bundle exec bookbinder generate cloud-documentation

   Thebookbinder generate BOOKNAME command creates a directory namedBOOKNAME.This directory contains the following:

   • A Gemfile referencing thebookbindery gem
   • A minimalconfig.yml file
   • Abin directory containing code
   • Amaster_middleman/source directory containing an index page
   • An emptymaster_middleman/build/ directory

2. After runningbookbinder generate, runbookbinder bind local to assembleyour book from the repositories specified in theconfig.yml file.

   Note: At this point, unless you've added anything to theconfig.yml,theconfig.yml contains no references to any repositories, and so bookbinder willbind a book with no content.

3. Run the following commands to start up the web site locally:

   • cd final_app
   • rackup

4. Launch a web browser tohttp://localhost:9292/ to view your book.

As typically used, the disparate source materials of a book are organized into separate git repositories.

When writing documentation on your local machine, however, we recommend that youadd uncommitted changes to the preview web site that you serve on your machine.

Thebind local command performs this operation by gathering local sections from sibling directories of your book.These sections' directories must have the same name as their remote git repositories, but don't need to be git repositoriesfor all commands.

You can optionally require a username and password to access any book served by runningrackup infinal_app by settingthe following environment variables:

• export SITE_AUTH_USERNAME=<your-book-username>
• export SITE_AUTH_PASSWORD=<your-book-password>

If these environment variables are not set, basic auth is not enabled.

• Create an AWS bucket for green builds and put info intocredentials.yml
• Set up CF spaces for staging and production and put details intocredentials.yml
• Deploy to production
• (Optional) Register your sitemap with Google Webmaster Tools

book_repo:org-name/repo-namecred_repo:org-name/private-repolayout_repo:org-name/master-middleman-reposections:  -repository:name:org-name/bird-reporef:165c28e967d58e6ff23a882689c953954a7b588ddirectory:birdssubnav_template:cool-sidebar-partial# optional  -repository:name:org-name/reptile-reporef:d07101dec08a698932ef0aa2fc36316d6f7c4851directory:reptilesproduct_id:my_product# optionalproducts:# optional  -id:my_productsubnav_root:reptiles/indexarchive_menu:# optional  -v1.3.0.0  -v1.2.0.0:archive-repo/your_pdf.ymlpublic_host:animals.example.comtemplate_variables:# optionalvar_name:special-valueother_var:12

Assuming your book is in git, your.gitignore should contain the followingentries, which are directories generated by Bookbinder:

outputfinal_app

master_middleman is a directory which forms the basis of your site.Middleman configuration and top-level assets, javascripts, and stylesheets should all be placed in here. You can also have ERB layout files. Each time a bind operation is run, this directory is copied tooutput/master_middleman. Then each section repository is copied (as a directory) intooutput/master_middleman/source/, before middleman is run to generate the final app.

.ruby-version is used byRuby version managers to select the appropriate Ruby version for a given project.

Bookbinder now supports breaking the above config.yml across multiple files.

A non-empty config.yml is still required in the book's root directory, however you may optionally include any number of valid yaml files with config in a directory namedconfig, which you will need to create. At runtime, configuration will be loaded fromconfig.yml and any files matching*.yml in theconfig directory.

The credentials repository should be a private repository, referenced in yourconfig.yml ascred_repo. It containscredentials.yml, which must include your deployment credentials:

aws:access_key:AKIAIOSFODNN7EXAMPLEsecret_key:wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEYgreen_builds_bucket:s3_bucket_namecloud_foundry:username:sampassword:pelapi_endpoint:https://api.run.pivotal.ioorganization:documentation-teamapp_name:docsenv:staging:space:docs-staginghost:cfapps.io:        -staging-route-subdomain        -another-staging-route-subdomainproduction:space:docs-productionhost:cfapps.io:        -production-route-subdomain

If you specify alayout_repo: inconfig.yml with the full name of a git repository (e.g.,cloudfoundry/my-doc-layout, which will default to GitHub), it will be downloaded for use as your book'smaster_middleman directory.

Any files included in your book'smaster_middleman/source directory will override files of the same name in the specified layout repository.

By default, thebookbinder bind remote command binds the most current versions (i.e., themaster branch) of the documents in the git repositories specified by thesections: of yourconfig.yml.

Bookbinder supports aref key to enable use of an alternate version of a repository. The value of this key can be the name of a branch (e.g.,develop), a SHA, or a tag (v19).

sections:  - repository:      name: org-name/bird-repo      ref: my-branch

Example SHA:

sections:  - repository:      name: org-name/bird-repo      ref: 165c28e967d58e6ff23a882689c953954a7b588d

Bookbinder supports alayout_repo_ref key to enable use of an alternate version of a layout repository. The value of this key can be the name of a branch (e.g.,develop), a SHA, or a tag (v19).

layout_repo: cloudfoundry/my-doc-layoutlayout_repo_ref: v19

Note: Bookbinder only uses theref key when binding 'remote'. Thebookbinder bind local command ignores theref key.

You can optionally specify a directory inside a source repository to use as a section with theat_path key, as follows:

sections:  - repository:      name: org-name/bird-repo      at_path: scrub/jay    directory: birds    subnav_template: cool-sidebar-partial

In the above example, the contents of thebird-repo/scrub/jay directory would be made available atbirds on your bound book.

• Markdown
• DITA

All markdown sections must be specified within the section key of theconfig.yml.

Bookbinder supports YAMLfrontmatter. Frontmatter (or "front matter") allows you to include page-specific variables in YAML format at the top of a markdown file.

If you want to include front matter in a markdown file, create a block at the top of the file by adding two lines of triple hyphens:---. Inside this block, you can create new data accessible to Bookbinder using thecurrent_page.data hash. For example, if you addtitle: "My Title", Bookbinder can accesscurrent_page.data.title to read "My Title".

Bookbinder currently supports the following front matter when binding books:

• title: Specifies the title of HTML page.
• owner: Specifies the owner of a topic. This can be a single owner, or multiple owners.

Example of front matter for a topic with one owner:

---title: Understanding Cloud Foundryowner: Cloud Foundry Concepts Team---

Example of front matter for a topic with three owners:

---title: Using Cloud Foundry Services with the CLIowner:  - Services Team  - Command Line Interface Team  - Documentation Team---

Specify the following in theconfig.yml:

• All DITA sections within the dita_sections key of theconfig.yml
• In either the first or in each (for multiple ditamaps) DITA section listed in theconfig.yml, a key-value pair "ditamap_location: my-ditamap.ditamap"
• (optional) In either the first or in each (for multiple ditamaps) DITA section listed in theconfig.yml, a key-value pair "ditaval_location: my-ditaval.ditaval"

For example:

dita_sections:  -repository:name:org-name/bird-reporef:165c28e967d58e6ff23a882689c953954a7b588d#optionaldirectory:birdsditamap_location:path/to/my-special-ditamap-location.ditamapditaval_location:path/to/my-special-ditaval-location.ditaval#optional -repository:name:org-name/dependent-sectionref:165c28e967d58e6ff23a882689c123998a7b577e#optionaldirectory:dependent-sectionditamap_location:path/to/other-ditamap.ditamapditaval_location:path/to/other-ditamap.ditaval#optional

Note: You'll need to have properly installed and specified theDITA-OT library.

If adita_section requires support DITA files from another repository, you can specify the support repository beneath adependent_sections key in the parent repository.

Dependent sections are cloned into the parent section's directory. In the following example, the content from the dependent section will be available at<your-domain>/birds/dinosaurs/.

dita_sections:  - repository:      name: org-name/bird-repo      ref: 165c28e967d58e6ff23a882689c953954a7b588d    directory: birds    ditamap_location: path/to/my-special-ditamap-location.ditamap    ditaval_location: path/to/my-special-ditaval-location.ditaval    dependent_sections:    - repository:        name: org-name/dinosaur-repo        ref: pterodactyl      directory: dinosaurs

Bookbinder supports ERB tags if they are specified as unicode:<%= is<%= and%> is%>. This enables use ofhelper functions.

If you want to render ERB tags as text and not evaluated as code by the Ruby interpreter, you must escape the opening ERB tag with a backslash as follows:<%= is escaped as<\%=. This functionality is useful for code examples, for instance.

Render a link with the URL of the current page's source repository and the text 'View the source for this page in GitHub'.

Inconfig.yml, add:

repo_link_enabled: true

Note: This feature renders a link to a file with either the extension.html.md.erb for Markdown source files, or the extension.xml for DITA source files. Ensure that all of your files have appropriate extensions.

For this helper to render the link, you must pass the helper a whitelist of the environments where you want the link to display.

For example, suppose you have an application with staging and production environments available at 'example-staging.cfapps.io' and 'example-production.cfapps.io', and you only want this link to display in the staging environment. Whitelist staging as an included environment as illustrated in thesection below.

You can add the source repository link to thesource/layouts/layout.erb file in the master_middleman directory or in the layout repository, or to the bottom of an individual page. For example, you can add the line<%= render_repo_link(include_environments: ['staging']) %> in the desired location for your link to include the link only on sites with 'staging' in their URLs.

If you include the line below in yoursource/layouts/layout.erb, the source repository partial will be rendered on every page of your book that has not been specifically excluded:

<%= render_repo_link(include_environments: [<your-environments]) %>

To specifically exclude the repository link from being rendered on a page, add the line<% exclude_repo_link %> to the desired page.

For flexibility, the product name (a long version and a short one) and version are defined as variables. Here's how to use them:

Define these three variables inconfig.yml:

template_variables:  - product_name_long: Apache Geode  - product_name: Geode  - product_version: 1.2

Use the following Ruby syntax to refer to these variables everywhereexcept intitle: lines:

<%=vars.product_name %><%=vars.product_name_long %><%=vars.product_version %>

You can't use these variables intitle: lines. Here's the workaround:

Instead of:

---title: Apache Geode 1.2 Documentation---

Do this:

<% set_title(product_name_long, product_version, "Documentation") %>

Why? Because thetitle: construct is not Ruby code, it's YAML, and it cannot interpret Ruby variables.

Cautions:

• Begin with<%, not<%=. (We're invoking a function, not printing its value.)
• Do not put a space before the opening parenthesis (useset_title() notset_title ().)
• Do not quote the three product variable names (product_name,product_name_long, andproduct_version).Do quote all other text.

You can add CSS styles directly to a page using traditional<style> tags directly below the page frontmatter (immediately before the page content).

---title: A Christmas Carol, Stave One---<style>    h1.unusual {        font-size: x-small;    }</style>Your text here.

Render a feedback form on your book's pages.

Inconfig.yml, add:

feedback_enabled: true

When feedback is enabled in this way, a POST endpoint is created at/api/feedback on your server, which will send a formatted email via the SendGrid Mail API. Accepted parameters for the post include:date,page_url,comments, andis_helpful.

Required credentials will need to be set in your environment for the feature to send mail. These include:SENDGRID_USERNAME,SENDGRID_API_KEY,FEEDBACK_TO,FEEDBACK_FROM.

1. In the master_middleman dir or the layout repositorysource/layouts/layout.erb file, or on an individual page where you want the feedback form, add<%= yield_for_feedback %>. If you include<%= yield_for_feedback %> in yoursource/layouts/layout.erb, the feedback partial will be rendered on every page of your book.

2. Create a partial named_feedback.erb that is your feedback form, and any JavaScript required to send a valid POST to the endpoint configured above.

You can choose to not have the feedback form render on specified pages if you add the following line<%= exclude_feedback %> above<%= yield_for_feedback %>.

Use this functionality if you included<%= yield_for_feedback %> in yoursource/layouts/layout.erb and want to exclude the partial from certain pages.

Bookbinder comes with a Middleman configuration that provides a handful of helpful functions, and should work for most book projects. To use a custom Middleman configuration instead, place aconfig.rb file in themaster_middleman directory of the book project. This will overwrite Bookbinder'sconfig.rb.

Bookbinder provides several helper functions that can be called from within an.erb file in a doc repository, such as a layout file.

<%= quick_links %> produces a table of contents based on in-page anchors.

<%= modified_date %> displays the most recent commit date for the file in the format 'Page last updated: September 1, 2015'. You can provide an optional date format, i.e.<%= modified_date '%m/%d/%y'%>.

Themodified_date helper uses the date of the most recent commit that does not contain the text "[exclude]" in its commit message.

Themermaid_diagram helper accepts a block including text formatted to generateMermaid diagrams. In order to use this helper, includethe Mermaid package in your book.

<% mermaid_diagram do%> graph TB         subgraph one         a1-->a2         end         subgraph two         b1-->b2         end         subgraph three         c1-->c2         end         c1-->a2<% end %>

<%= breadcrumbs %> generates a series of breadcrumbs as a UL HTML tag. The breadcrumbs go up to the site's top-level, based on the title of each page. The bottom-most entry in the list of breadcrumbs represents the current page; the rest of the breadcrumbs show the hierarchy of directories that the page lives in. Each breadcrumb above the current page is generated by looking at thefrontmatter title of the index template of that directory. If you'd like to use breadcrumb text that is different than the title, an optional 'breadcrumb' attribute can be used in the frontmatter section to override the title.

<%= yield_for_subnav %> inserts the appropriate subnav based on each constituent repositories'subnav_template: orproduct_id: parameter inconfig.yml. For a given section, only one key should be used. If both keys are specified, bookbinder will default to using the subnav_template.

The default template (\_default.erb) uses the labeldefault and is applied to all sections unless another template is specified with subnav_template or subnav_name. Template labels are the name of the template file with extensions removed. ("sample" for a template named "sample.erb")

If your book includes a dita_section, Bookbinder will automatically look for a filesubnav_template.erb frommaster_middleman/source/subnavs. No additional keys are necessary in yourconfig.yml.

Bookbinder makes subnav links available in a JSON format at/subnavs/dita_subnav_<your-dita-section-directory>-props.json. They could be consumed with a JavaScript library (e.g. React.js) to create your subnav. Bookbinder will have written the name of the file containing the links fromsubnav_template.erb at a data attribute called data-props-location on 'div.nav-content'.

An example of the JSON links:

{  "links":  [    {"url": "/dita-section-one/some-guide.html", "text": "my topic 1"},    {"url": "/dita-section-one/../dita-section-dependency/some-guide-1.html", "text": "my topic dependency"}  ]}

Note: Use of_dita_subnav_template.erb is deprecated as of Bookbindery 7.2.0. If your DITA subnavs currently rely on this file, simply rename it tosubnav_template.erb in the same location.

If specified for a section, Bookbinder will look for a file of name .erb inmaster_middleman/source/subnavs and insert this partial into the template at the code helper.

sections:  -repository:name:org-name/bird-repodirectory:birdssubnav_template:subnav-about-birds

Specifyingsubnav_root under theproducts key and associating this to a section viaproduct_id generates navigation-related json by parsing the HTML file specified bysubnav_root for any linked H2s and spidering to those linked pages to make a subnav tree. This json can then be consumed with a javascript library (e.g. React.js) to create your subnav.

This feature not currently supported for DITA, though thesubnav_template key does something very similar when used in dita_sections (see above).

Requirements:

• Inconfig.yml: aproduct_id key for each section to display the generated subnav, and aproducts section that defines eachproduct_id (as keyid) used for those sections.
• Properly formatted page for eachsubnav_root

sections:  -repository:name:org-name/bird-repodirectory:birdsproduct_id:my_product  -repository:name:org-name/reptile-repodirectory:reptilesproduct_id:my_productproducts:  -id:my_productsubnav_root:reptiles/index

Keys:

• id: Links a given section to its product in the config. Should contain no spaces.
• subnav_root: Root file to be parsed for to-be-generated subnavs.

Example subnav_root:

To generate a subnav,bookbinder starts spidering from thesubnav_root, followinga elements with thesubnav class. This creates a JSON file with the subnav contents, described in more detail below.

reptiles/index.html.md:

<ahref="./thing-one.html"class="subnav">My First Nav Item</a>Some text that won't be in the Nav##<ahref="./thing-two.html"class="subnav">My Second Nav Item</a>

Note that the links can be anywhere on the page (the second link is in anh2, for instance), but will be followed in order.

reptiles/thing-one.html:

- <ahref="./nested-thing.html"class="subnav">My Nested Nav Item</a>

reptiles/thing-two.html:

##Won't Show Up in the NavNothing to see here.

reptiles/nested-thing.html:

##End of the lineNo more.

<%= yield_for_code_snippet from: 'my-org/code-repo', at: 'myCodeSnippetA' %> inserts code snippets extracted from code repositories.

To delimit where a code snippet begins and ends, you must use the format ofcode_snippet MARKER_OF_YOUR_CHOOSING start OPTIONAL_LANGUAGE, followed by the code, and then finishing withcode_snippet MARKER_OF_YOUR_CHOOSING end.If you omit theOPTIONAL_LANGUAGE, your snippet will still be formatted as code but will not have any syntax highlighting.

Code snippet example:

; code_snippet myCodeSnippetA start clojure(deffib-seq     (lazy-cat [01] (map + (rest fib-seq) fib-seq)))user> (take20 fib-seq)(01123581321345589144233377610987159725844181); code_snippet myCodeSnippetA end

To insert a code snippet from a GitHub repository, you must add the repository as adependent section resource in theconfig.yml of the book. Thedependent section in theconfig.yml must end with ano-docs: true statement.

Example excerpt from aconfig.yml:

- repository:    name: cloudfoundry/docs-buildpacks  directory: buildpacks  dependent_sections:  - repository:      name: cloudfoundry-samples/pong_matcher_grails  - repository:      name: cloudfoundry-samples/pong_matcher_groovy  - repository:      name: cloudfoundry-samples/pong_matcher_spring  - repository:      name: cloudfoundry-samples/pong_matcher_ruby    no-docs: true

The above YAML adds four GitHub repositories as "dependent sections" todocs-buildpacks in thedocs-book-cloudfoundry book. These are the repositories referenced by theyield_for_code_snippet in the buildpack topics.

Bookbinder allows you to specify a drop-down menu template for use in the navbar. This can contain links to PDFs or other archived versions of documentation. To specify a drop-down menu, add thearchive_menu key inconfig.yml as follows:

  archive_menu:    - v1.3.0.0    - v1.2.0.0: my-pdf-repo/v1.2.0.0.pdf

The first key (e.g. v1.3.0.0) is available for use as a title in your navbar. You can configure the structure of the drop-down menu by creating a template inmaster_middleman/source/archive_menus/_default.erb.

Finally, to insert the archive menu, use the<%= yield_for_archive_drop_down_menu %> tag in the appropriate part of the navbar in your layout.erb.

Bookbinder allows you to definetemplate variables by adding key-value pairs to theconfig.yml file for your book.

To use a template variable, add the key to a source file.When you then bind your book, Bookbinder replaces the key with the value defined in theconfig.yml file.

• To define a new template variable, add the key-value pair to thetemplate_variables section of theconfig.yml file.

  Exampleconfig.yml file excerpt:

    ...  template_variables:    app_domain: example.com    my-app: < a href="http://my-app.example.org" >this link

• To use a template variable, add the key (in <%=vars.MY-KEY%> form) to a source file.

  Example source file excerpt:

    I deployed my app to <%=vars.app_domain%>. You can see it by clicking <%=vars.my-app%>.

Bookbinder supportspartials, reusable blocks of source material.

Create a partial by adding a file containing source material to a repository.The name of the file must start with an underscore.

To use the partial, use the name of the file without the starting underscore in the following code, and add this code to the source file where you want the partial to appear: <%= partial 'FILENAME' %>

Bookbinder also includes helper code to correctly find image, stylesheet, and javascript assets. When using<% image_tag ...,<% stylesheet_link_tag ..., or<% javascript_include_tag ... to include assets, Bookbinder will search the entire directory structure starting at the top-level until it finds an asset with the provided name. For example, when resolving<% image_tag 'great_dane.png' %> called from the pagedogs/big_dogs/index.html.md.erb, Middleman will first look inimages/great_dane.png. If that file does not exist, it will trydogs/images/great_dane.png, thendogs/big_dogs/images/great_dane.png.

Bookbinder's entry point is thebookbinder executable. It should be invoked from the book directory. The following commands are available:

Bookbinder's most important command isbind. It takes one argument on the command line:local orremote.

    bin/bookbinder bind local

will find documentation repositories in directories that are siblings to your current directory.

    bin/bookbinder bind remote

will find doc repositories by downloading the latest version from git. Note that if any of the repositories configured as 'sections' are private, you shouldcreate an SSH key for Bookbinder from an account that has access to the section repositories.

You shouldssh-add this key to give Bookbinder access to the repositories.

The bind command creates two output directories, one namedoutput/ and one namedfinal_app/. These are placed in the current directory and are overwritten each time you run Bookbinder.

Note: When Bookbinder binds DITA sections of your book, it only sends error messages to the screen. Use the--verbose option withbind to see the non-filter output.

final_app/ contains Bookbinder's ultimate output: a Rack web-app that can be pushed to Cloud Foundry or run locally.

The Rack web-app will respect redirect rules specified inredirects.rb, so long as they conform to therack/rewritesyntax. For example:

rewrite'/wiki/John_Trupiano','/john'r301'/wiki/Yair_Flicker','/yair'r302'/wiki/Greg_Jastrab','/greg'r301%r{/wiki/(\w+)_\w+},'/$1'

output/ contains an intermediary state. This includesoutput/master_middleman, the final prepared directory that thebind script ran middleman against.

Bookbinder's command for live previews in development iswatch. Its functionality is similar tobind local in that it only includes repositories stored on disk. It then watches the sections (not the book or layout repositories) for changes and runs a preview server that updates upon file save.

    bin/bookbinder watch

Note: CPU usage directly relates to the number of sections your book is watching. If you find that watch is running slowly, either usebind or delete unused local repositories.

Bookbinder's command for generating PDFs from books isimprint. It is currently only supported for DITA, and requires DITA-OT to beinstalled locally. Generated PDFs will be deposited inartifacts/pdf.

It takes one argument on the command line:local orremote.

    bin/bookbinder imprint local

will find documentation repositories in directories that are siblings to your current directory.

    bin/bookbinder imprint remote

will find doc repositories by downloading the latest version from git.

Optionally and simliar tobind, it also takes--verbose and--dita-flags. There is a known bug with the--dita-flags flag that requires escaped quotes surrounding any passed arguments, like so:--dita-flags=\"my=argument other=argument\".

Imprint looks in the config.yml for content specified aspdf_sections, as so:

pdf_sections:- repository:    name: org/content  ditamap_location: content.ditamap  ditaval_location: content.ditaval  output_filename: awesome-pdf- repository:    name: org/more-content  ditamap_location: more-content.ditamap  ditaval_location: more-content.ditaval

Runningimprint with the config specified above will result in the creation of two pdfs, one called 'awesome-pdf.pdf', as specified underoutput_filename, and the other defaulting to the name of the ditamap, 'more-content.pdf'.

For snapshotting books at specific point in time, Bookbinder provides thepunch command. This command git tags your book, all sections specified in theconfig.yml, and the layout repository (if provided) at the current head of master.

It takes one argument on the command line: the name of the tag you'd like to add.

    bin/bookbinder punch <tag-name>

Note that in order to tag any remote repositories, you will require push access. If you have not already, you shouldcreate an SSH key andssh-add the key for Bookbinder from an account that has push access to the repositories.

As a convenience, Bookbinder provides a command to update all your local doc repositories, performing a git pull on each one:

    bin/bookbinder update_local_doc_repos

cd final_appbundlerackup

This will start arack server to serve yourdocumentation website locally athttp://localhost:9292/. While making edits indocumentation repositories, we recommend leaving this running in a dedicated shellwindow. It can be terminated by hittingctrl-c.

The sitemap file/sitemap.xml is automatically regenerated when binding. When setting up a new docs website, make sure to add this sitemap's url in Google Webmaster Tools (for better reindexing?).

To run bookbinder's rspec suite, install binstubs, then run the included rake task:

Once:bundle install --binstubs

Then at any time:bin/rake