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).
In your book.json add the plugin: `json { "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:
$3
If you want to configure the caption text, you can provide your own template in the form:
`_CAPTION_` will be automatically replaced by the title or alt of your image (the plugin uses first `title`, if not found, then `alt` attribute).
$3
Keywords
`_PAGE_LEVEL_`, `_PAGE_IMAGE_NUMBER_` and `_BOOK_IMAGE_NUMBER_` are available.`json "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`.
$3
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:
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:`json "pluginsConfig": { "image-captions": { "images": { "1.2.2": { "caption": "This is a special image: _CAPTION_" } } } } `
$3
Similarly, you can specify image tag attributes globally or at specific image levels:
0.3.0, image list is available from book variables. You need to define a variable name:`json "pluginsConfig": { "image-captions": { "variable_name": "pictures" } } `
This will automatic add image container to the book variables, so that they are present on any page:
`json "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
* 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:
` 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:`json { "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:
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.
$3
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.
$3
This plugin is based on the example plugin from GitbookIO/plugin.
$3
#### 0.4.0 - Compatibility with Gitbook 3.x (while keeping also compatibility with 2.x releases of Gitbook) #8.
#### 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_``
