docs: label new features introduced in `v0.4` (#1138)

In #1058, I noted: > Tangentially related work: > ... > - better annotate new features (motivated by writing these docs) > - we should add "New" to new features :) > - we should note when a feature was introduced (I think this is a core part of most software documentation) > - we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge > This came up again in https://github.com/just-the-docs/just-the-docs/discussions/1136#discussioncomment-4716253, so I think it's best for us to resolve this sooner rather than later. This PR is me doing that. I: - have added a headings-level "New" label to every new heading introduced since `v0.3` - added, when possible, inline YAML comments when new configuration options have been introduced I did this by scanning through the CHANGELOG and selecting each feature that is either tagged with `Add` and has documentation. I may have also missed any new features, so some double-checking would be helpful!

docs: label new features introduced in `v0.4` (#1138)
5f91e326 · Matt Wang · GitHub · 975aec07 · 5f91e326 · 5f91e326
Unverified Commit 5f91e326 authored 2 years ago by Matt Wang Committed by GitHub 2 years ago
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -69,6 +69,10 @@ search:
 ```

 ## Mermaid Diagrams
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 The minimum configuration requires the key for `version` ([from jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)) in `_config.yml`:

@@ -104,6 +108,10 @@ heading_anchors: true
 ```

 ## External navigation links
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 External links can be added to the navigation through the `nav_external_links` option.
 See [Navigation Structure]({% link docs/navigation-structure.md %}#external-navigation-links) for more details.
@@ -165,6 +173,10 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 See [Customization]({% link docs/customization.md %}) for more information.

 ## Callouts
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.:

@@ -231,6 +243,12 @@ ga_tracking: UA-2709176-10
 ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
 ```

+### Multiple IDs
+{: .d-inline-block .no_toc }
+
+New (v0.4.0)
+{: .label .label-green }
+
 This theme supports multiple comma-separated tracking IDs. This helps seamlessly transition UA properties to GA4 properties by tracking both for a while.

 ```yaml
@@ -267,7 +285,7 @@ just_the_docs:
      # nav_exclude: true
      # Fold the collection in the navigation
      # Supports true or false (default)
-      # nav_fold: true
+      # nav_fold: true  # note: this option is new in v0.4
      # Exclude the collection from the search
      # Supports true or false (default)
      # search_exclude: true

--- a/docs/customization.md
+++ b/docs/customization.md
@@ -16,10 +16,6 @@ nav_order: 6
 ---

 ## Color schemes
-{: .d-inline-block }
-
-New
-{: .label .label-green }

 Just the Docs supports two color schemes: light (default), and dark.

@@ -166,6 +162,10 @@ To do this, create an `_includes` directory and make a copy of the specific file
 Just the Docs provides the following custom includes files:

 ### Custom TOC Heading
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 `_includes/toc_heading_custom.html`

@@ -202,12 +202,20 @@ The `<head>` tag automatically includes a link to an existing favicon if you set
 Content added to this file appears at the top of every page's main content between the site search and auxiliary links if they are enabled. If `search_enabled` were set to false and `aux_links` were removed, the content of `header_custom.html` would occupy the space at the top of every page.

 ### Custom Nav Footer
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 `_includes/nav_footer_custom.html`

 Any content added to this file will appear at the bottom left of the page below the site's navigation. By default an attribution to Just the Docs is displayed which reads, `This site uses Just the Docs, a documentation theme for Jekyll.`.

 ### Custom Search Placeholder
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 `_includes/search_placeholder_custom.html`


--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -145,6 +145,10 @@ nav_order: 2
 The Buttons page appears as a child of UI Components and appears second in the UI Components section.

 ### Ordering child pages
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 You can optionally add the following to the YAML front matter to reverse the default sort order of child pages:


--- a/docs/search.md
+++ b/docs/search.md
@@ -127,6 +127,13 @@ This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses
 Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json).

 ## Custom content for search index
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+Advanced
+{: .label .label-yellow }

 By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`. Other data (e.g. front matter, files in `_data` and `assets`) is not indexed. Users can customize what is indexed.


--- a/docs/ui-components/callouts.md
+++ b/docs/ui-components/callouts.md
@@ -6,6 +6,10 @@ nav_order: 7
 ---

 # Callouts
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes).


--- a/docs/ui-components/code.md
+++ b/docs/ui-components/code.md
@@ -90,6 +90,10 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 ---

 ## Mermaid diagram code blocks
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 [Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.

@@ -145,6 +149,10 @@ graph TD;
 *Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.*

 ## Copy button
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }

 The copy button for code blocks can be enabled or disabled via the `enable_copy_code_button` key in `_config.yml`. By default, the value of this key is `false`; users need to opt-in.

@@ -153,4 +161,4 @@ The copy button for code blocks can be enabled or disabled via the `enable_copy_
 enable_copy_code_button: true
 ```

-Note that this feature requires JavaScript; if JavaScript is disabled in the browser, this feature will not work.
\ No newline at end of file
+Note that this feature requires JavaScript; if JavaScript is disabled in the browser, this feature will not work.