|
| 1 | +--- |
| 2 | +glightbox.auto_caption: true |
| 3 | +--- |
| 4 | + |
| 5 | +# Caption |
| 6 | + |
| 7 | +Built-in GLightbox caption with title and description can be used by adding attributes: ```data-title```, ```data-description``` through markdown_extensions ```attr_list```. Enable ```attr_list``` via ```mkdocs.yml```: |
| 8 | + |
| 9 | +```yaml |
| 10 | +markdown_extensions: |
| 11 | + - attr_list |
| 12 | +``` |
| 13 | +
|
| 14 | +Check more detail about ```attr_list``` on the [official document](https://python-markdown.github.io/extensions/attr_list/). |
| 15 | + |
| 16 | +!!! warning "Warning" |
| 17 | + |
| 18 | + When the title or the description has been set, the plugin setting of lightbox image ```height``` and ```width``` will be overridden as ```100vh```. |
| 19 | + |
| 20 | +## Usage |
| 21 | + |
| 22 | +### Title and description attributes |
| 23 | + |
| 24 | +```markdown title="Setting title and description with attributes" |
| 25 | +{ data-title="Madeira, Portugal." data-description="Madeira, an autonomous region of Portugal, is an archipelago comprising 4 islands off the northwest coast of Africa. - Google" } |
| 26 | +``` |
| 27 | + |
| 28 | +<div class="result" markdown> |
| 29 | +<figure markdown> |
| 30 | + |
| 31 | +{ width="500px" data-title="Madeira, Portugal." data-description="Madeira, an autonomous region of Portugal, is an archipelago comprising 4 islands off the northwest coast of Africa. - Google" } |
| 32 | + |
| 33 | +<figcaption>Madeira, Portugal. Credit: Blueswen</figcaption> |
| 34 | +</figure> |
| 35 | +</div> |
| 36 | + |
| 37 | +### Caption position |
| 38 | + |
| 39 | +Caption position can be changed with plugin option ```caption_position``` globally or individually by attribute ```data-caption-position```. |
| 40 | + |
| 41 | +```markdown title="Setting position with data-caption-position" |
| 42 | +{ data-title="Cabo da Roca, Portugal. Credit: Blueswen" data-description=".custom-desc1" data-caption-position="right"} |
| 43 | +``` |
| 44 | + |
| 45 | +<div class="result" markdown> |
| 46 | +<figure markdown> |
| 47 | +{ width="400px" data-title="Cabo da Roca, Portugal. Credit: Blueswen" data-description="Monument announcing Cabo da Roca as the westernmost point of continental Europe" data-caption-position="right"} |
| 48 | +<figcaption>Cabo da Roca, Portugal. Credit: Blueswen</figcaption> |
| 49 | +</figure> |
| 50 | +</div> |
| 51 | + |
| 52 | +### Advanced description |
| 53 | + |
| 54 | +For a longer description, you can add a ```div``` with class ```glightbox-desc``` and a custom class name which be assigned in ```data-description``` with a prefix ```.```. The content in div will be used as the description. |
| 55 | + |
| 56 | +```html title="Advanced Description" |
| 57 | +{ width="500px" data-title="Cabo da Roca, Portugal. Credit: Blueswen" data-description=".custom-desc1" } |
| 58 | +
|
| 59 | +<div class="glightbox-desc custom-desc1"> |
| 60 | + <p>Saint George's Castle is a historic castle in the Portuguese capital of Lisbon, located in the freguesia of Santa Maria Maior.</p> |
| 61 | + <p>Human occupation of the castle hill dates to at least the 8th century BC while the first fortifications built date from the 1st century BC.</p> |
| 62 | +</div> |
| 63 | +``` |
| 64 | + |
| 65 | +<div class="result" markdown> |
| 66 | +<figure markdown> |
| 67 | +{ width="500px" data-title="Cabo da Roca, Portugal. Credit: Blueswen" data-description=".custom-desc1" } |
| 68 | +<figcaption>Castelo de São Jorge, Lisbon, Portugal. Credit: Blueswen</figcaption> |
| 69 | +</figure> |
| 70 | + |
| 71 | +<div class="glightbox-desc custom-desc1"> |
| 72 | +<p>Saint George's Castle is a historic castle in the Portuguese capital of Lisbon, located in the freguesia of Santa Maria Maior.</p> |
| 73 | +<p>Human occupation of the castle hill dates to at least the 8th century BC while the first fortifications built date from the 1st century BC.</p> |
| 74 | +</div> |
| 75 | +</div> |
| 76 | + |
| 77 | +### Image alt as the caption |
| 78 | + |
| 79 | +Since adding a title attribute to each image may be frustrating, we provide an ```auto_caption``` option to use the image alt as the default title. |
| 80 | + |
| 81 | +- Globally: Enable the ```auto_caption``` plugin option in ```mkdocs.yml``` to affect whole mkdocs |
| 82 | + |
| 83 | + ```yaml |
| 84 | + plugins: |
| 85 | + - glightbox: |
| 86 | + auto_caption: true |
| 87 | + ``` |
| 88 | + |
| 89 | +- Locally: Add page metadata ```glightbox.auto_caption: true``` through markdown_extensions ```meta``` setting page meta on a specific page. Enable ```meta``` via ```mkdocs.yml```: |
| 90 | + |
| 91 | + ```yaml |
| 92 | + markdown_extensions: |
| 93 | + - meta |
| 94 | + ``` |
| 95 | + |
| 96 | + Check more detail about ```meta``` on the [official document](https://python-markdown.github.io/extensions/meta_data/). |
| 97 | + |
| 98 | +```markdown title="Using image alt as caption title with page meta" |
| 99 | +--- |
| 100 | +glightbox.auto_caption: true |
| 101 | +--- |
| 102 | +
|
| 103 | + |
| 104 | +``` |
| 105 | + |
| 106 | +<div class="result" markdown> |
| 107 | +<figure markdown> |
| 108 | + |
| 109 | +{ width="500px"} |
| 110 | + |
| 111 | +<figcaption>Yosemite, USA. Credit: Blueswen</figcaption> |
| 112 | +</figure> |
| 113 | +</div> |
0 commit comments