Update documentation

coatless-quarto · Oct 20, 2024 · dfa902a · dfa902a
1 parent da9d0a1
commit dfa902a
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 66 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,11 @@
 # Custom Callout Extension For Quarto <img src="https://github.com/user-attachments/assets/7edadf64-a304-436c-b54f-2f76def14c14" align ="right" alt="" width ="150"/>
 
-> [!IMPORTANT]
->
-> This extension is under development and is not yet ready for use.
-
-The `custom-callout` extension provides a YAML interface to configure a Quarto Callout Block with custom values.
+The `{quarto-custom-callout}` extension provides a YAML interface to configure a 
+Quarto Callout Block with custom values.
 
 ## Installing
 
-To install the `custom-callout` extension, follow these steps:
+To install the `{quarto-custom-callout}` extension, follow these steps:
 
 1. Open your terminal.
 2. Navigate to your Quarto project directory.
@@ -23,19 +20,21 @@ If you're using version control, you will want to check in this directory.
 
 ## Using
 
-The `custom-callout` extension allows you to define custom callouts in your YAML front matter and then use them in your Quarto documents.
+The `custom-callout` extension allows you to define custom callouts in your 
+YAML front matter and then use them in your Quarto documents.
 Here's a quick overview of the available YAML options:
 
 | Option | Description | Example |
 |--------|-------------|---------|
 | `title` | Default title for the callout (optional) | `title: "Important Note"` |
-| `icon` | Use a default icon (optional) | `icon: true` |
+| `icon` | Use a default icon (optional) | `icon: "true"` |
 | `icon-symbol` | Custom symbol or text for the icon | `icon-symbol: "📝"` |
 | `color` | Color for the callout's left border and icon | `color: "#FFA500"` |
-| `appearance` | Callout appearance (optional) | `appearance: simple` |
-| `collapse` | Make the callout collapsible (optional) | `collapse: true` |
+| `appearance` | Callout appearance (optional) | `appearance: "simple"` |
+| `collapse` | Make the callout collapsible (optional) | `collapse: "true"` |
 
-You can start using custom callouts in your Quarto project immediately after installation. First, define your custom callouts in the YAML front matter:
+You can start using custom callouts in your Quarto project immediately
+after installation. First, define your custom callouts in the YAML front matter:
 
 ```yaml
 custom-callout:
@@ -51,7 +50,7 @@ filters:
 ```
 
 
-Then, use the custom callouts in your Markdown content:
+Then, use the custom callouts in your Quarto document like this:
 
 ```markdown
 ::: todo
@@ -63,31 +62,25 @@ This information is crucial for understanding the concept.
 :::
 ```
 
-## Examples
-
-Here are some examples of custom callouts in action:
+The above example will render two custom callouts in your document: 
+one with a pink border and a "📝" icon and the other with an orange
+border and a "⚠️" icon. 
 
-::: {.todo}
-This is a custom 'todo' callout with a pink border and a pencil icon.
-:::
 
-::: {.test}
-This is a custom 'test' callout with an orange border and a warning icon.
-:::
+## Notes
 
+The `{quarto-custom-callout}` extension uses Quarto's [`quarto.Callout` custom AST Node](https://quarto.org/docs/prerelease/1.3/custom-ast-nodes/callout.html) to create custom [Quarto Callouts](https://quarto.org/docs/authoring/callouts.html).
 
-## References
+Previously, there were two approaches to creating custom callouts. Both approaches rely on using a `Div` node. Specifically, we have:
 
-There has been a lot of work done on the `callout` block in Quarto. Here are some references:
+1. Create custom CSS classes with the necessary styling and apply it to a `Div` node.
+2. Use [`{quarto-custom-numbered-blocks}`](https://github.com/ute/custom-numbered-blocks) extension by [Ute Hahn](https://github.com/ute). 
 
-- Discussion/Issue Tickets:
-   - [Custom filter for processing Github/Obsidian style callouts stopped working - any tips? ](https://github.com/quarto-dev/quarto-cli/discussions/6550)
-   - [Creating new callout types (and sharing as an extension)?](https://github.com/quarto-dev/quarto-cli/discussions/7753)
-   - [Custom callout boxes](https://github.com/quarto-dev/quarto-cli/issues/844)   
-- Official
-   - [Quarto: Callout Lua API Reference](https://quarto.org/docs/prerelease/1.3/custom-ast-nodes/callout.html)
-   - [Quarto: Callout Blocks](https://quarto.org/docs/authoring/callouts.html)
+The latter approach is more user-friendly and allows for the creation of 
+custom number blocks with a YAML interface. Further, it offers immense flexibility 
+in terms of styling and customization compared to the `quarto.Callout()` 
+custom AST Node used by `{quarto-custom-callout}`. For example, if you need
+grouped callouts, you can use the `groups` option in the 
+`{quarto-custom-numbered-blocks}` extension to formulate joint counters and styles.
+It's a great extension to use if you need more than just custom callouts.
 
-- Source Code
-    - SCSS: <https://github.com/quarto-dev/quarto-cli/blob/71945532e1fc1a5cf113117f6d5ff5bee3991797/src/resources/formats/html/bootstrap/_bootstrap-rules.scss#L1520-L1620>
-    - LaTeX: <https://github.com/quarto-dev/quarto-cli/blob/71945532e1fc1a5cf113117f6d5ff5bee3991797/src/resources/filters/quarto-pre/meta.lua#L11>
diff --git a/docs/index.qmd b/docs/index.qmd
@@ -42,11 +42,11 @@ Here's a quick overview of the available YAML options:
 | Option | Description | Example |
 |--------|-------------|---------|
 | `title` | Default title for the callout (optional) | `title: "Important Note"` |
-| `icon` | Use a default icon (optional) | `icon: true` |
+| `icon` | Use a default icon (optional) | `icon: "true"` |
 | `icon-symbol` | Custom symbol or text for the icon | `icon-symbol: "📝"` |
 | `color` | Color for the callout's left border and icon | `color: "#FFA500"` |
-| `appearance` | Callout appearance (optional) | `appearance: simple` |
-| `collapse` | Make the callout collapsible (optional) | `collapse: true` |
+| `appearance` | Callout appearance (optional) | `appearance: "simple"` |
+| `collapse` | Make the callout collapsible (optional) | `collapse: "true"` |
 
 You can start using custom callouts in your Quarto project immediately after installation. First, define your custom callouts in the YAML front matter:
 
@@ -64,7 +64,7 @@ filters:
 ```
 
 
-Then, use the custom callouts in your Markdown content:
+Then, use the custom callouts in your Quarto documents like this:
 
 ```markdown
 ::: todo
@@ -74,6 +74,11 @@ Remember to complete this section.
 ::: test
 This information is crucial for understanding the concept.
 :::
+
+
+::: {.todo title="Collapsed Custom Todo (Click to Expand)" collapse="true"}
+This is a custom 'todo' callout that is collapsible and has a custom title.
+:::
 ```
 
 ## Examples
@@ -84,6 +89,18 @@ Here are some examples of custom callouts in action:
 This is a custom 'todo' callout with a pink border and a pencil icon.
 :::
 
+::: {.todo title="Collapsed Custom Todo (Click to Expand)" collapse="true"}
+This is a custom 'todo' callout that is collapsible and has a custom title.
+:::
+
+::: {.todo title="Simple Appearance Custom Todo" appearance="simple"}
+This is a custom 'todo' callout that uses a **simple** appearance with a custom title.
+:::
+
+::: {.todo title="Simple Appearance Custom Todo" appearance="minimal"}
+This is a custom 'todo' callout that uses a **minimal** appearance with a custom title.
+:::
+
 ::: {.test}
 This is a custom 'test' callout with an orange border and a warning icon.
 :::

diff --git a/docs/qcustom-callout-faq.qmd b/docs/qcustom-callout-faq.qmd
@@ -130,16 +130,30 @@ The custom-callout extension is primarily designed for HTML output. While it may
 the full range of customization options (especially custom icons and colors) might not be available in non-HTML outputs.
 
 
-## How does the custom-callout extension compare to the quarto-custom-numbered-blocks extension?
+## How does the quarto-custom-callout extension compare to the quarto-custom-numbered-blocks extension?
 
-The [quarto-custom-numbered-blocks](https://github.com/ute/custom-numbered-blocks) extension by [Ute Hahn](https://github.com/ute) is a complementary tool that offers different functionality:
+The [quarto-custom-numbered-blocks](https://github.com/ute/custom-numbered-blocks) extension by [Ute Hahn](https://github.com/ute) is a complementary tool that offers different functionality. It creates numbered blocks (e.g., theorems, examples) with automatic numbering and cross-referencing. Other features include: 
 
-- It creates numbered blocks (e.g., theorems, examples) with automatic numbering and cross-referencing.
-- Features include: 
-  - Automatic numbering and cross-referencing
-  - Grouping of block types with shared styling and numbering
-  - Generation of lists of specific block types
-  - Support for both PDF and HTML output
-- This makes it great for academic or technical documents requiring numbered theorems, examples, or exercises.
+- Grouping of block types with shared styling and numbering
+- Generation of lists of specific block types
+- Support for both PDF and HTML output
+
+This makes it great for academic or technical documents requiring numbered theorems, examples, or exercises. Both extensions can be used in the same document if needed, but be mindful of potential styling conflicts and filter ordering.
+
+One notable difference is that the `quarto-custom-callout` extension is built ontop of Quarto's built-in callout functionality, while `quarto-custom-numbered-blocks` creates its own block type.
+
+## Where can I find more information about custom callouts?
+
+For more information about custom callouts, you can refer to the following resources:
+
+- Discussion/Issue Tickets:
+   - [Custom filter for processing Github/Obsidian style callouts stopped working - any tips? ](https://github.com/quarto-dev/quarto-cli/discussions/6550)
+   - [Creating new callout types (and sharing as an extension)?](https://github.com/quarto-dev/quarto-cli/discussions/7753)
+   - [Custom callout boxes](https://github.com/quarto-dev/quarto-cli/issues/844)   
+- Quarto Documentation
+   - [Quarto: Callout Lua API Reference](https://quarto.org/docs/prerelease/1.3/custom-ast-nodes/callout.html)
+   - [Quarto: Callout Blocks](https://quarto.org/docs/authoring/callouts.html)
+- Quarto Source Code
+    - SCSS: <https://github.com/quarto-dev/quarto-cli/blob/71945532e1fc1a5cf113117f6d5ff5bee3991797/src/resources/formats/html/bootstrap/_bootstrap-rules.scss#L1520-L1620>
+    - LaTeX: <https://github.com/quarto-dev/quarto-cli/blob/71945532e1fc1a5cf113117f6d5ff5bee3991797/src/resources/filters/quarto-pre/meta.lua#L11>
 
-Both extensions can be used in the same document if needed, but be mindful of potential styling conflicts and filter ordering.
diff --git a/example.qmd b/example.qmd
@@ -17,16 +17,6 @@ custom-callout:
     title: "Test feature"
     icon: true
     color: "#801410"
-  fancytest:
-    icon: true
-    title: "Test feature"
-    icon-symbol: "fa-thumbs-up"
-    color: "#801410"
-  not-great:
-    icon: false
-    title: "Not great"
-    icon-symbol: "fa-thumbs-down"
-    color: "#801410"
 filters:
   - custom-callout
 ---
@@ -43,15 +33,6 @@ Please address this issue ...
 Let's do a feature test!
 :::
 
-::: fancytest
-Test fontawesome icon
-:::
-
-
-::: not-great
-Test fontawesome icon
-:::
-
 ::: {.callout-note}
 Hello!
 :::