Use HTML for admonitions (#2367)

config/mkdocs-offline.yml

@@ -155,6 +155,7 @@ nav:
     - Contributing:
       - Writing Guide:
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
         - 'meta/translations.md'
       - Technical Guides:

config/mkdocs.en.yml

@@ -142,6 +142,7 @@ nav:
     - Contributing:
       - Writing Guide:
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
         - 'meta/translations.md'
       - Technical Guides:

config/mkdocs.es.yml

@@ -104,6 +104,7 @@ nav:
       - 'dns.md'
       - 'email.md'
       - 'financial-services.md'
+      - 'photo-management.md'
       - 'search-engines.md'
       - 'vpn.md'
     - Software:
@@ -139,6 +140,7 @@ nav:
     - Contribuir:
       - "Guía de redacción":
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
         - 'meta/translations.md'
       - "Guías técnicas":

config/mkdocs.fr.yml

@@ -140,6 +140,7 @@ nav:
     - "Contribuer":
       - "Guide de rédaction":
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
         - 'meta/translations.md'
       - "Guides techniques":

config/mkdocs.he.yml

@@ -144,6 +144,7 @@ nav:
     - Contributing:
       - Writing Guide:
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
         - 'meta/translations.md'
       - Technical Guides:

config/mkdocs.it.yml

@@ -104,6 +104,7 @@ nav:
       - 'dns.md'
       - 'email.md'
       - 'financial-services.md'
+      - 'photo-management.md'
       - 'search-engines.md'
       - 'vpn.md'
     - Software:
@@ -139,6 +140,7 @@ nav:
     - Contribuisci:
       - Guida alla scrittura:
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
         - 'meta/translations.md'
       - Guide tecniche:

config/mkdocs.nl.yml

@@ -140,6 +140,7 @@ nav:
     - Bijdragen:
       - Schrijfgids:
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
         - 'meta/translations.md'
       - Technische gids:

config/mkdocs.ru.yml

@@ -106,6 +106,7 @@ nav:
       - 'dns.md'
       - 'email.md'
       - 'financial-services.md'
+      - 'photo-management.md'
       - 'search-engines.md'
       - 'vpn.md'
     - Программное обеспечение:
@@ -141,7 +142,9 @@ nav:
     - Помощь проекту:
       - Руководство по написанию:
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - Технические руководства:
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

config/mkdocs.zh-Hant.yml

@@ -106,6 +106,7 @@ nav:
       - 'dns.md'
       - 'email.md'
       - 'financial-services.md'
+      - 'photo-management.md'
       - 'search-engines.md'
       - 'vpn.md'
     - 軟體:
@@ -141,7 +142,9 @@ nav:
     - 貢獻:
       - 寫作指南:
         - 'meta/writing-style.md'
+        - 'meta/admonitions.md'
         - 'meta/brand.md'
+        - 'meta/translations.md'
       - 技術指導:
         - 'meta/uploading-images.md'
         - 'meta/git-recommendations.md'

docs/meta/admonitions.md

@@ -0,0 +1,287 @@
+---
+title: Admonitions
+---
+
+**Admonitions** (or "call-outs") are a choice writers can use to include side content in an article without interrupting the document flow.
+
+<div class="admonition example" markdown>
+<p class="admonition-title">Example Admonition</p>
+
+This is an example of an admonition. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
+
+</div>
+
+<details class="example" markdown>
+<summary>Example Collapsible Admonition</summary>
+
+This is an example of a collapsible admonition. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
+
+</details>
+
+## Formatting
+
+To add an admonition to a page, you can use the following code:
+
+```markdown title="Admonition"
+<div class="admonition TYPE" markdown>
+<p class="admonition-title">TITLE</p>
+
+ENCLOSED TEXT
+
+</div>
+```
+
+```markdown title="Collapsible Admonition"
+<details class="TYPE" markdown>
+<summary>TITLE</summary>
+
+ENCLOSED TEXT
+
+</details>
+```
+
+The `TITLE` must be specified, if you don't want a specific title you can set it to the same text as the `TYPE` (see below) in title case, e.g. `Note`. The `ENCLOSED TEXT` should be Markdown formatted.
+
+### Regular types
+
+Replace `TYPE` in the examples above with one of the following:
+
+#### `note`
+
+<div class="admonition note" markdown>
+<p class="admonition-title">Note</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `abstract`
+
+<div class="admonition abstract" markdown>
+<p class="admonition-title">Abstract</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `info`
+
+<div class="admonition info" markdown>
+<p class="admonition-title">Info</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `tip`
+
+<div class="admonition tip" markdown>
+<p class="admonition-title">Tip</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `success`
+
+<div class="admonition success" markdown>
+<p class="admonition-title">Success</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `question`
+
+<div class="admonition question" markdown>
+<p class="admonition-title">Question</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `warning`
+
+<div class="admonition warning" markdown>
+<p class="admonition-title">Warning</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `failure`
+
+<div class="admonition failure" markdown>
+<p class="admonition-title">Failure</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `danger`
+
+<div class="admonition danger" markdown>
+<p class="admonition-title">Danger</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `bug`
+
+<div class="admonition bug" markdown>
+<p class="admonition-title">Bug</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `example`
+
+<div class="admonition example" markdown>
+<p class="admonition-title">Example</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+#### `quote`
+
+<div class="admonition quote" markdown>
+<p class="admonition-title">Quote</p>
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+</div>
+
+### Special Types
+
+#### `recommendation`
+
+This format is used to generate recommendation cards. Notably it is missing the `<p class="admonition-title">` element.
+
+``` markdown title="Recommendation Card"
+<div class="admonition recommendation" markdown>
+
+![PhotoPrism logo](assets/img/photo-management/photoprism.svg){ align=right }
+
+**PhotoPrism** is a self-hostable platform for managing photos. It supports album syncing and sharing as well as a variety of other [features](https://www.photoprism.app/features). It does not include E2EE, so it's best hosted on a server that you trust and is under your control.
+
+[:octicons-home-16: Homepage](https://www.photoprism.app){ .md-button .md-button--primary }
+[:octicons-eye-16:](https://www.photoprism.app/privacy){ .card-link title="Privacy Policy" }
+[:octicons-info-16:](https://www.photoprism.app/kb){ .card-link title=Documentation}
+[:octicons-code-16:](https://github.com/photoprism){ .card-link title="Source Code" }
+
+<details class="downloads" markdown>
+<summary>Downloads</summary>
+
+- [:simple-github: GitHub](https://github.com/photoprism)
+
+</details>
+
+</div>
+```
+
+<div class="result" markdown>
+
+<div class="admonition recommendation" markdown>
+
+![PhotoPrism logo](../assets/img/photo-management/photoprism.svg){ align=right }
+
+**PhotoPrism** is a self-hostable platform for managing photos. It supports album syncing and sharing as well as a variety of other [features](https://www.photoprism.app/features). It does not include E2EE, so it's best hosted on a server that you trust and is under your control.
+
+[:octicons-home-16: Homepage](https://www.photoprism.app){ .md-button .md-button--primary }
+[:octicons-eye-16:](https://www.photoprism.app/privacy){ .card-link title="Privacy Policy" }
+[:octicons-info-16:](https://www.photoprism.app/kb){ .card-link title=Documentation}
+[:octicons-code-16:](https://github.com/photoprism){ .card-link title="Source Code" }
+
+<details class="downloads" markdown>
+<summary>Downloads</summary>
+
+- [:simple-github: GitHub](https://github.com/photoprism)
+
+</details>
+
+</div>
+
+</div>
+
+#### `downloads`
+
+This is a special type of collapsible admonition, used to generate the download links section. It is only used within recommendation cards, as shown in the example above.
+
+```markdown title="Downloads Section"
+<details class="downloads" markdown>
+<summary>Downloads</summary>
+
+- [:simple-googleplay: Google Play](https://play.google.com/store/apps/details?id=ch.protonmail.android)
+- [:simple-appstore: App Store](https://apps.apple.com/app/apple-store/id979659905)
+- [:simple-github: GitHub](https://github.com/ProtonMail/proton-mail-android/releases)
+- [:simple-windows11: Windows](https://proton.me/mail/bridge#download)
+- [:simple-apple: macOS](https://proton.me/mail/bridge#download)
+- [:simple-linux: Linux](https://proton.me/mail/bridge#download)
+- [:octicons-browser-16: Web](https://mail.proton.me)
+
+</details>
+```
+
+<div class="result" markdown>
+
+<details class="downloads" markdown>
+<summary>Downloads</summary>
+
+- [:simple-googleplay: Google Play](https://play.google.com/store/apps/details?id=ch.protonmail.android)
+- [:simple-appstore: App Store](https://apps.apple.com/app/apple-store/id979659905)
+- [:simple-github: GitHub](https://github.com/ProtonMail/proton-mail-android/releases)
+- [:simple-windows11: Windows](https://proton.me/mail/bridge#download)
+- [:simple-apple: macOS](https://proton.me/mail/bridge#download)
+- [:simple-linux: Linux](https://proton.me/mail/bridge#download)
+- [:octicons-browser-16: Web](https://mail.proton.me)
+
+</details>
+
+</div>
+
+## Old Format
+
+Throughout the site, you may see some admonitions formatted similarly to these examples:
+
+``` markdown title="Admonition"
+!!! note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+!!! note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+</div>
+
+``` markdown title="Collapsible Admonition"
+??? example "Custom Title"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+??? example "Custom Title"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+</div>
+
+**This format is no longer used going forward,** because it is incompatible with newer versions of our translation software at Crowdin. When adding a new page to the site, only the newer HTML-based format should be used.
+
+There is no rush to convert admonitions with the old format to the new format. Pages currently using this formatting should continue to work, but we will be updating them to use the newer HTML-based format above over time as we continue to update the site.