kubernetes-handbook/gitbook-plugin-image-captions/README.md

GitBook Image Captions Plugin

Add nice generated captions to your book images. This plugin converts alt or title attributes of your images into the captions. Works on both the GitBook website and your own generated book (pdf, mobi).

Online demo

→ http://tdvorak.gitbooks.io/test-book/content/phetchaburi.html

Installation

In your book.json add the plugin:

{
    "plugins": [
        "image-captions"
    ]
}

If you're building your book locally, download and prepare plugins by simply running gitbook install.

Configuration

The plugin provides reasonable defaults and configuration is not needed. However, there are several config values you can use to adapt captions to your needs:

Caption text

If you want to configure the caption text, you can provide your own template in the form:

  "pluginsConfig": {
      "image-captions": {
          "caption": "Image - _CAPTION_"
      }
  }

The keyword _CAPTION_ will be automatically replaced by the title or alt of your image (the plugin uses first title, if not found, then alt attribute).

Page level and image number

Keywords _PAGE_LEVEL_, _PAGE_IMAGE_NUMBER_ and _BOOK_IMAGE_NUMBER_ are available.

  "pluginsConfig": {
      "image-captions": {
          "caption": "Image _PAGE_LEVEL_._PAGE_IMAGE_NUMBER_ - _CAPTION_"
      }
  }

Available variables in the caption text:

• _PAGE_LEVEL_: for example 1.2. Follows chapters numbering.
• _PAGE_IMAGE_NUMBER_: sequence number of the image in the chapter. First image in chapter gets value 1.
• _BOOK_IMAGE_NUMBER_: sequence number of the image in the whole book. First image in book gets value 1.

Text alignment

The image caption is by default aligned to the center. You can override this setting by providing a config property align with one of the values:

• left
• right

This will align the caption to the left:

  "pluginsConfig": {
      "image-captions": {
          "align": "left"
      }
  }

Image specific captions

You can set up caption template for a specific image by image level. Level is constructed from page level and image order so that on subpage 1.2 second image level is: 1.2.2. That can be used as an index on configuration:

  "pluginsConfig": {
    "image-captions": {
      "images": {
        "1.2.2": {
          "caption": "This is a special image: _CAPTION_"
        }
      }
    }
  }

Additional image attributes

Similarly, you can specify image tag attributes globally or at specific image levels:

  "pluginsConfig": {
    "image-captions": {
      "attributes": { "width": "300" },
      "images": {
        "1.2.2": {
          "attributes": {
            "width": "400"
          }
        }
      }
    }
  }

Skip selected images

You can specify which images should be skipped and not enriched by a figure caption:

  "pluginsConfig": {
    "image-captions": {
      "images": {
        "1.2.2": {
          "skip": true
        }
      }
    }
  }

Image list

As of version 0.3.0, image list is available from book variables. You need to define a variable name:

  "pluginsConfig": {
    "image-captions": {
      "variable_name": "pictures"
    }
  }

This will automatic add image container to the book variables, so that they are present on any page:

    "variables": {
        "pictures": []
    }

Note: it is not necessary to add pictures entry on variables. This is just to clarify usage of the image list. By defining variable_name, you can make sure not to overwrite any previous book variable.

All images are available on any page. Say you have a pictures.md, you can do:

  # Pictures

  {% for picture in book.pictures %}
    1. [{{ picture.list_caption }}]({{ picture.backlink }})
  {% endfor %}

Image properties available in addition to list_caption and backlink are:

• backlink: link back to the image page containing anchor
• list_caption: image caption get from alt or title attribute and processed for list image label
• index: index of an image on a page aka. page wide image number
• src: image src attribute
• key: image key concatenated by page_level.index
• page_level: page level of the image
• caption: image caption get from alt or title attribute
• nro: book wide image number

You can set a different caption (label) for each image on a list. This makes it possible to separate page image caption at the actual page from the label of the image on a picture list:

  "pluginsConfig": {
    "image-captions": {
      "variable_name": "pictures",
      "list_caption": "List image _BOOK_IMAGE_NUMBER_: _CAPTION_"
    }
  }

You can set a specific image caption / label as well:

  "pluginsConfig": {
    "image-captions": {
      "variable_name": "pictures",
      "images": {
        "1.2.2": {
          "list_caption": "Special list image _PAGE_LEVEL_._PAGE_IMAGE_NUMBER_: _CAPTION_"
        }
      }
    }
  }

CSS Styles

This plugin generates simple figure around your images:

<figure>
    <img src="../images/phetchaburi.jpg" alt="Phra Nakhon Khiri, Phetchaburi">
    <figcaption>Image - Phra Nakhon Khiri, Phetchaburi</figcaption>
</figure>

You can then customize CSS styles of the figure and figcaption. By default, this definition is included in the plugin:

figure {
    margin: 1.5em 0px;
    padding:10px 0;
}

figcaption {
    clear: left;
    margin: 0.75em 0px;
    text-align: center;
    font-style: italic;
    line-height: 1.5em;
}

You can attach your own styles by following the guide on help.gitbook.com.

First, you have to create your own css file - for example website.css. Then add your definitions of figure and caption. You can change the text align, colors, borders and so one. Last step is to attach your css style to the book. Open the book.json config file and modify it to look similar to this:

{
  "plugins": [
    "image-captions"
  ],
  "pluginsConfig": {},
  "styles": {
    "website": "website.css"
  }
}

Different styles can be attached for web and books, so you can style the captions differently for every medium:

"styles": {
  "website": "website.css",
  "ebook": "ebook.css",
  "pdf":  "pdf.css",
  "mobi": "ebook.css",
  "epub": "ebook.css"
}

The same should apply for the online book editor on gitbook.com.

Under the hood

This plugin attaches itself to the "page" event of GitBook generate task. It receives rendered HTML page of the chapter. Then the plugin goes through the HTML code of the page, searching for images. If there is any image detected, containing also alt or title atribute, the plugin replaces image occurences with the figure tag, including original image and additional figcaption tag with the text read from image attributes.

Tests

Important part of this plugin is the test suite. You can run the test with command:

npm test

The test suite includes JSHint validation of the plugin and test suite itself. Then the Mocha integration tests are executed, validating expected plugin bahavior. Integration tests use gitbook-tester.

The tests are executed with every pushed commit on the Travis-CI server.

Based on

This plugin is based on the example plugin from GitbookIO/plugin.

Changes

0.4.0

• Compatibility with Gitbook 3.x (while keeping also compatibility with 2.x releases of Gitbook) #8.

Thanks @piranna and @SamyPesse for support.

0.3.3 & 0.3.4

• Fixes for #7

Thanks @ghuntley and @aschempp for reports and verification.

0.3.2

• Readme spelling and grammar fixes (#5)
• Fixed possible issue with processing pages (promises) (#6)

Thanks @klauern for #5 and @markomanninen for #6

0.3.1

• Fixed figure inside a link (#4)

Thanks @michaellwest for reporting this issue!

0.3.0

• added support for book wide and page wide image numbering
• added support for image specific caption and attribute configuration
• added support for image list construction by book variables
• new template keywords: _PAGE_LEVEL_, _PAGE_IMAGE_NUMBER_, _BOOK_IMAGE_NUMBER_ in addition to _CAPTION_

Thanks @markomanninen for all new features!

0.2.0

• Paragraphs and inline image

Thanks @aschempp for PR #1 and new test cases!

0.1.0

• figcaption text-align configurable

0.0.2 - 0.0.6

• dependencies fix
• dependencies cleanup, readme update
• npmignore configuration
• integration with coverage tools, readme, code cleanup
• initial commit