It would be nice to have easy access to additional icons, e.g. code languages and brands, and invoke them in the same/similar way to how we invoke Material icons. The current solution is to add icons as you would any other image, which usually results in poor-looking icons that don't support light/dark mode out of the box.

Maybe this was a conscious design choice (I don't remember), but usually the symbol for an unordered list item changes depending on the level of nesting. Currently all levels of nesting use the same disc symbol (see preview). Whereas the AsciiDoc/Antora default UIs (example) use disc, circle, and then square for all subsequent levels.

JIRA: DOC-3966

To provide a better user experience for CQL users, we should support CQL language syntax highlighting in code blocks.

Background

The DataStax docs have never had true CQL highlighting. Like the Astra Portal UI, the docs site previously used the SQL definition behind the scenes (the current docs UI doesn't provide any highlighting for CQL). But while the SQL and CQL grammars are similar, they are not the same, and it's important for DataStax as a company to provide the best docs experience for CQL users.

Unfortunately, there is no CQL definition available for highlight.js or any of the common highlighter libraries. Luckily, Therapon Skoteiniotis created an initial beta of a highlight.js language definition for CQL: https://github.com/riptano/highlightjs-cql.

The definition should be considered BETA for now. Not all of the syntax has been tested and some highlighting might appear incorrect (there are a lot of context sensitive keywords in SQL in general and CQL inherits some of it).

Requirements

1. Complete the repo setup.

• Should align with best practices of other 3rd party highlightjs definition projects. See Language contributor checklist and SUPPORTED_LANGUAGES.md.
• The CI works for PRs. The CI will not work for publishing to NPM since we do not have a TOKEN from a valid account in NPM. So that will fail at the moment.
• The links in the package.json file (to issues and homepages) are a guess since we're not sure which organization the repo will eventually live in yet, or whether it will be made public.

2. Test the definition against Cassandra 4 CQL grammar and fix any reported issues.
3. Import the library into the Docs UI.

Stretch goals

1. Test and update the definition to support the Cassandra 5 CQL grammar. The definition should support the vector type and any other CQL changes in Cassandra 5.
2. Open-source the definition and publish to NPM under the official DataStax account.

• Potentially move the repo to the https://github.com/datastax org.
• Submit a PR to add the definition to SUPPORTED_LANGUAGES.md.

3. If there's a need, work with the FE team to integrate the highlighter into the Astra Portal UI. (Probably requires porting the definition to Prism.)

We have a legacy ticket open to enhance our old Antora UI to provide clickable icons for custom anchors (DOC-4076). This was a feature that existed in the old DITA UI but did not get ported into our Antora UI.

The request is to provide clickable anchor link icons, like the auto-generated ones we currently have on section titles, but on elements where a custom AsciiDoc ID has been defined. These can be block and inline elements, such as list items, tables, etc.

NOTE: This issue should probably be worked on in conjunction with #120.

In AsciiDoc, you can add links to images. However, when the link is an external link, the automatic external link styling implemented in Automatic External Links applies a box arrow icon to the image. This is undesirable, and we should update the CSS to ignore external links when they're a part of an image.

There are certain pages in the docs where we may need to display equations and other types of math. Currently, we have to manually create SVG files to present this kind of information, which is labor-intensive to create, update, and make compatible with our CSS styles.

To alleviate this problem, the AsciiDoc language provides STEM support for embedding math-mode macros from LaTeX and/or AsciiMath notation as block or inline elements (see docs-ui preview). These elements act as passthroughs to preserve the expressions as entered. The expressions are then passed on to the converter to be processed and rendered for display using a STEM provider (e.g., MathJax).

The STEM provider must be configured in the output converter to render the expressions. As far as implementation goes, we should thoroughly review the discussion in Antora Issue #184 and investigate the options presented. The simplest approach would probably be to load MathJax via CDN on just the pages that use stem. (That's the approach the Apache Cassandra project went with: apache/cassandra-website#215.) However, as pointed out in the Antora discussion, using a CDN is a security risk. But coming up with an offline alternative might be tricky. The offline approach presented in this comment might be a good place to start since it appears to have the semi-endorsement of the Antora maintainers.

Similar to the Load your data page, we need to add tabs for Astra Portal, Python, TypeScript, and Java to the applicable sections of the Perform a vector search page.

Note: The goal of this ticket is to allow the svg macro to be used for inline images. This is not to be confused with the opts=inline SVG attribute, which the svg macro already uses by default.

The svg macro syntax currently supports inline usage (svg:) and block usage (svg::). However, it appears that the macro only truly supports block images. This limits the macro's versatility and causes confusion for writers when the inline usage produces unexpected results.

Inline image support

There are cases where we'd like to be able to use the macro for inline images. For example, to achieve a table that looks like the following:

You would expect the syntax to look like this:

|===
|Embedding provider |External |Astra-hosted |Docs

|svg:ROOT:ui/icons/microsoft-azure-openai.svg[] Azure OpenAI <-- Macro inline with text
|[.material-icons]#check#
|
|xref:integrations:embedding-providers/azure-openai.adoc[Get started]
|===

However, because the macro generates a block image, the inline text gets bumped down into a new paragraph below the icon:

Feature parity with built-in image:: and image: macros

It would be ideal if the svg: and svg:: macro usages mirrored their image: and image:: counterparts in terms of their supported attributes and values.

There are two major issues with the left nav.

Parent nav items can't be links

The UI currently doesn't support the following nav configuration:

* xref:parent-page.adoc[]
** xref:child-page.adoc[]

The parent page doesn't present as a link. This has forced us to use an undesirable workaround of making the parent page a child of itself, for example:

* Parent page
** xref:parent-page.adoc[]
** xref:child-page.adoc[]

A list title is required

IMPORTANT: As @mlr pointed out below, this should be fixed as of #103.

Currently, the UI requires the nav to have at least one list title element, otherwise it won't render anything at all.

✅ Does render

.Some title
* xref:page-1.adoc
* xref:page-2.adoc
* xref:page-3.adoc
* xref:page-4.adoc

❌ Does not render

* xref:page-1.adoc
* xref:page-2.adoc
* xref:page-3.adoc
* xref:page-4.adoc

Some products don't have enough pages to warrant using list titles. However, we've had to add at least one so that nav will at least show the pages in the first place:

We need to give some love to the collapsible block.

Current styling:

The current styling doesn't match the original spec.

Original spec:

Collapsible results

In the past we've used tabsets to show a command and its output/results in separate tabs (example):

However, this presents a problem since many of our code examples span multiple API clients. If someone can switch between Python, TypeScript, and Java, we would need to provide separate results for each client and this gets messy.

The current workaround is to switch to using a collapsible section underneath the corresponding code block. In fact, the original spec actually hinted at this workaround:

This was a late addition to the spec that didn't get much discussion and was never implemented in the new UI. The downside of a collapsible block is that it currently presents a small clickable target that isn't as easy to notice/use as tabs are.

We should consider enhancing the UI to treat command + results as a special case that warrants its own special UI treatment. If possible, we should consider implementing this on the AsciiDoc side in such a way that doesn't require (but still allows) using the full collapsible block syntax.

There are any number of reasons that hover-over popups would be a great addition to these docs. Popups for glossary terms, or additional explanation that would be cumbersome in the text. File pathnames, that sort of thing.

Have you considered adding that capability to the publishing?

Here are examples:

1. http://creativeindividual.co.uk/2011/02/create-a-pop-up-div-in-jquery/
2. This is actually a click-on popup from old DSE docs:
   

The UI currently gets its favicon by referencing www.datastax.com/favicon.ico. See head-meta.hbs:

<link rel="icon" href="https://www.datastax.com/favicon.ico">

The benefit of this approach, in theory, is that we would always display the same favicon as WWW. However, Marketing recently updated the favicon to a .png file, which resulted in the favicon 404'ing on all of our docs pages.

Marketing temporarily restored the previous file for us, but going forward we need to make a decision: Update the URL to use favicon.png, or start self-hosting the favicon in our own UI.

I think it's highly unlikely that the WWW favicon URL will change again unless/until web standards start favoring a different file format (.ico files were in use for over two decades). However, if we want to take an offline-first approach for the sake of durability and archivability, then it probably makes sense to start self-hosting.

If we go the self-hosted route, the Antora Default UI provides the following example (modified for PNG):

<link rel="icon" href="{{{uiRootPath}}}/img/favicon.png" type="image/png">

Since our site is published to docs.datastax.com/en, the above example would put the favicon at docs.datastax.com/en/_/img/favicon.png. I assume this is fine, but we'd want to confirm that it's ok not to have our favicon at the site root.

The DataStax Docs banner image should link to actual docs homepage: https://docs.datastax.com/en/home/docs/index.html

Currently, it links to the Serverless/Vector landing page: https://docs.datastax.com/en/astra/astra-db-vector/index.html

Hi. When viewed in light-mode vector docs, the 20x20px icon to the left of the topic's title looks like a white square. Compare with dark mode.

Original Basecamp task: https://3.basecamp.com/5214332/buckets/27604022/card_tables/cards/6687556414
Original reporter: @djsauble

The :page-colab-link:, :page-time-commitment:, :page-skill-level:, and # steps UI components contain useful information, but they're using a lot of valuable real estate right now. There's a ~100px high strip of screen under the title that's occupied by this information right now. Let's find a more efficient way to display it.

Some ideas:

• Shrink the space requirements (e.g. from ~100px to ~40px)
• Move these components inline with the page title
  • Consider pushing the right nav down so the page title can take up the entire width of the screen (minus the primary nav). Then, put the time commitment, skill level, and # steps to the immediate right of the page title, and float the Colab link to the right of the page (inline with the page title).

Nav is a little wide - horizontal scrolls bar shows but doesn't scroll

Despite the fact that the glossary link is referencing the site.path (see here) the final build is still lacking the /en prefix.

As a result the docs pages link to /glossary instead of /en/glossary

I've attempted variations including double curly and using site.url but was not able to determine the cause. This seems to be the only place this occurs. I'm not sure if it has to do with the partial or what.

For the time being a redirect is relocating users to the correct page.

The Marketing team suggested that we update the format of the <title> tag for pages on the docs site. The goal is to make the titles more descriptive and useful when they appear in Google search results.

Currently, the page <title> tag is constructed as follows:

    <title>PAGE TITLE :: SITE TITLE</title>

• PAGE TITLE - the AsciiDoc page title (value following single = at the top of each adoc page)
• Two colons ::
• SITE TITLE - the Antora site title (site.title key in the playbook)

Marketing recommends the following format:

    <title>PAGE TITLE | COMPONENT TITLE | SITE TITLE</title>

• Adds the name of the component (product name) in which the page resides.
• Replaces the two colons with a vertical bar |.

Additional requirements

Marketing had some additional suggestions:

1. If the page title already contains the component title, then we should not include component title in the <title> tag.

   • If possible, we should try and implement a matching rule that looks for the component title within the page title, and if true, either removes or supresses the component title from the <title> tag of the page.
   • Currently, the titles of our landing pages are the same as the component titles. So if we can't implement the above solution, then we should try to at least remove the component title from the <title> tag of landing pages, specifically.

2. (DEFERRED - will open a separate issue for this in the future) In some cases, a component title might not be well-known or descriptive enough for all users. For example, some users may not know that Starlight for Kafka falls under the umbrella of "Streaming".

   • We should maybe look into whether it's possible to customize the format of the <title> tag for specific components. For example:

         <title>PAGE TITLE | COMPONENT TITLE | Streaming | SITE TITLE</title>

3. Apparently, studies show that click-through rate is higher for search results that are in title case (we use sentence case).

   • After some light searching, it doesn't seem to be common practice for documentation websites to use different cases for the <title> tag vs <h1>. Therefore, I think we should set aside this recommendation for the time being.

Algolia considerations

We need to look into why Algolia is presenting generic page titles in search analytics. It may be related to the page title tag. For more info, see the following Slack thread: https://datastax.slack.com/archives/C04B8E5LQ7L/p1710778039481909

When you expand a nav element, the expansion happens downward, and the content within a section animates upward. This is quite disorienting and doesn't make a ton of sense. Can we remove the animation on the content within a nav element?

Two things:

1. [bug] It appears that when at least two PRs are merged in rapid succession, the workflow creates the correct number of tags, but sets them both on the same (most recent?) commit. This results in multiple releases with the same content. See prod-6 and prod-7: https://github.com/riptano/docs-ui/releases
2. [enhancement] We probably shouldn't generate a new release for updates to preview-src/* and README.adoc.

We don't provide users with an easy way to identify which component they're currently viewing. This is a big problem for wayfinding (especially for users arriving from Google search), and will continue to be a problem even after we introduce the global nav.

A good first step would be to add the component title to the top of the left nav. It should probably also be a link to the component start page (same as the breadcrumb). If the component has a version switcher, the title should sit adjacent to the version dropdown toggle.

NOTE: we should make sure to test long component titles to ensure that long titles wrap appropriately.

Our current site search is powered by Algolia DocSearch. DocSearch is an off-the-shelf collection of a couple different Algolia components, optimized for relatively small documentation websites. DocSearch is way better than our previous Algolia implementation in almost every respect, including better/faster search results, as well as pre-built UI that comes has keyboard shortcuts and accessibility features.

However, although DocSearch is very powerful and easy to implement out of the box, it lacks customizability. In particular, it doesn't provide filtering and really allow for rich UI customization beyond color and component sizing.

We need to take a comprehensive look at our current site search experience to determine whether we want to make any further UX/UI enhancements (including product filtering) and create a list of those requirements. Once we have those requirements, we need to assess whether it's possible to satisfy those those requirements using DocSearch. If DocSearch isn't up to the task, then we'll need to build a new search experience from the ground up using standard Algolia components.

We need to support adding a tracking pixel to pages in the new UI. See DOC-4013 for requirements and historical context.

Note: here's the implementation in the legacy UI: riptano/antora-ui-docs#100

Our old UI has a feature that allows writers to place an interactive "slideshow" of images within a page. So far, this has only been utilized in the ZDM documentation. However, even though this feature hasn't been widely adopted in our other docs (and despite its very basic functionality), internal and external users have praised it for helping them understand a very complex process (ZDM) without having to vertically scroll through images.

In order for the ZDM docs to have parity in the new UI, we need to implement a similar feature in the new UI that offers an equivalent or better experience.

The widget is completely user-directed, and doesn't have (or need) automatic playback. It has basic navigation controls to move forward/backward between slides, and has the option to restart the slideshow on the last slide.

Because the slides are quite size-restricted within the widget, users can click on a slide to open it in a lightbox. Therefore to replicate the current UX, this feature will depend on #68.

Each "slide" consists of an image and a description. Here's the syntax:

[.swiper]
====
[.slide]
--
.Walk through the illustrated migration phases
Discover the migration concepts, software components, and sequence of operations.

image:migration-introduction9.png["Introductory page prompts you to click the Start button to begin the graphical presentation."]
--

...

[.slide]
-- 
.Phase 5: Connect directly to Target
In this phase, move your client applications off the ZDM Proxy and connect the apps directly to Target. Once that happens, the migration is complete.

image:migration-phase5ra9.png["Illustrates migration Phase 5, as summarized in the text. Back and Restart buttons are available for navigation within the graphic."]
--
====

Please update the footer of doc pages to (c) 2024. Still showing (c) 2023. Thanks guys.

For tabsets, the tab titles should have a more elegant text wrapping solution that allows tab titles to automatically scale appropriately across different width constraints.

We should probably set a minimum and maximum tab title width that looks good, and then allow for wrapping to a second line when the width is constrained. Not sure if we should allow wrapping to a third line, but we should set a maximum number of lines to wrap, after which the title overflows into ellipses (or something along those lines).

In AsciiDoc, there two important types of titles: section titles and block titles.

Section titles are prefixed with a section marker (=, ==, ===, ====), which indicates the HTML heading level for that section. In the current UI, section titles below H2 are not clearly differentiated. Although they have special spacing, they are not very visually distinct from one another, and they also tend to visually blend together with block titles and even bold paragraph text.

Block titles are any title placed on a block (line prefixed with a dot . above the block). This can be a title on a list, table, image, code snippet, admonition, sidebar, etc.. These title elements are often given unique styling depending on the type of block they're defined on. For example, image titles are placed below the image.

The differentiation problem is coming to a head with @djsauble's work to update the client references in https://github.com/riptano/astra-vector-docs/pull/311 (see example). The preferred design goes down to H4, but the headings just seem to get lost. This has the potential to be exacerbated by updates to the collapsible block in #94.

NOTE: This issue should probably be worked on in conjunction with #83.

We need to make some enhancements to the image lightbox (#68):

1. The lightbox doesn't currently support images that use the svg:: macro. This is problematic because we use this macro to support embedded SVGs that honor our CSS styles for light and dark mode (example).

2. We should probably add a background to the lightbox that's the same size as the image. Currently, images with transparent backgrounds look messy when overlaid on top of page content (example).
   

3. We need to be able to selectively turn off the lightbox for certain images (both block and inline images). We could probably handle this with a role similar to the remove-ext-icon role that we use for selectively disabling the external link icon.
   Currently, the lightbox is enabled for the badge icons on the Connection methods comparison page, which is a little silly:
   
   But more importantly, when we enable the lightbox for the svg:: macro, we'll need to be able to turn off the lightbox for the graphics on the landing page:
   

By default, images are constrained by the width of the article body. Users should have the ability to enlarge an image if they so choose. Our old UI has rudimentary lightbox library that allows the user to click an image to open a larger version in a lightbox. We should consider adding a similar feature to the new UI.

My preference would be to work with the Antora community on implementing Issue-140 (MR-126). Based on the conversation in the aforementioned merge request, it seems that there are still a few additional enhancements that need to be made.

NOTE: This enhancement is currently a dependency of #73. The lightbox library we choose should probably be used to power the interactive graphic in addition to the other images on the site.

unable to expand any of the parent sections for the nav on mobile. I tried multiple browsers.

There are several use-cases where we'd like to be able to deep link directly to a tab (or nested tab). For example, we'd like to be able to link directly to a particular client example (or even a nested tab within that client example).

For ease of use, the implementation should leverage the existing approach to creating anchors in AsciiDoc. There are a couple of open issues in the Asciidoctor Tabs project that appear to relate to this requirement:

• asciidoctor/asciidoctor-tabs#57
• asciidoctor/asciidoctor-tabs#58

We should do a holistic assessment of the technical requirements and determine whether certain parts of the implementation should depend on the extension itself rather than our own custom code. If we do our own custom implementation, there’s a chance that it might not play nice with future updates to the official extension (it’s still in beta, after all). If we determine that we are indeed dependent on upstream enhancements, we should probably open an issue in the Asciidoctor Tabs project (and/or comment on the existing issues noted above) to discuss our findings with the maintainers and potentially contribute the necessary enhancements.

Original Basecamp task: https://3.basecamp.com/5214332/buckets/27604022/card_tables/cards/6674999919
Original reporter: @mlr

Integration Logos

• Decrease size of logos
• Remove padding

Figma: https://www.figma.com/file/6Qnh8DNqFQcTtvfUseYPZP/%5BEXPL%5D-Vector-Priorities-2023-Vision-Work?type=design&node-id=598-2758&mode=design&t=bTKo2Hg9vDQ4bBam-4

Original Basecamp task: https://3.basecamp.com/5214332/buckets/27604022/card_tables/cards/6631472604
Original reporter: @colegoldsmith

Create a way to filter integrations home items by clicking on the tags or on the right side category list

https://www.figma.com/file/6Qnh8DNqFQcTtvfUseYPZP/%5BEXPLORATIONS%5D-Vector-Priorities-2023-Vision-Work?type=design&node-id=3454-27696&mode=design&t=nprMnTmU6Npj4Vjj-4

Original Basecamp task: https://3.basecamp.com/5214332/buckets/27604022/card_tables/cards/6675023270
Original reporter: @mlr

Is it possible to make tag links clickable?

When clicked should show pages that have those tags.

Figma: https://www.figma.com/file/6Qnh8DNqFQcTtvfUseYPZP/%5BEXPL%5D-Vector-Priorities-2023-Vision-Work?type=design&node-id=1794-6663&mode=design&t=bTKo2Hg9vDQ4bBam-4

Hey guys, let me know what you find.

For our Leftnav, in Light node, If i'm checking the correct set of foreground text color & background color hex # values, I think certain headings fail WCAG accessibility requirements.

https://webaim.org/resources/contrastchecker/?fcolor=8E9093&bcolor=F7F7F7

Do I have the right values?

Please refer to the leftnav when viewed from a page like https://docs.datastax.com/en/astra/astra-db-vector/api-reference/data-api-commands.html#advanced-feature-indexing-clause-on-createcollection , and the attached screenshot. I tried to inspect the css colors but not sure if I've got the right values in that webaim comparison.

If we fail accessibility color contrast, it could be difficult for people who have low vision or who are color blind.

There are any number of reasons that hover-over popups would be a great addition to these docs. Popups for glossary terms, or additional explanation that would be cumbersome in the text. File pathnames, that sort of thing.

Have you considered adding that capability to the publishing?

As part of #109, we updated the way page meta titles were constructed to avoid duplicate names appearing in the titles. However, it looks like we might not have applied the same logic to the titles used in social previews:

Reported by @toptobes:

Syntax highlighting breaks when you have an immediately-invoked function expression (IIFE) that's an arrow function:

Works fine with old-school function expressions:

All I can say is that when making an IIFE using an arrow function, it renders the body of it improperly (as shown in the first image), But for some reason, renders properly when you declare an interface before it (so I'd imagine it might work if you declare a class or type before it? Haven't tested it yet though.)

The bottom of the left nav has a gap where you can see the content as you scroll.

In the Google Developer Docs Style Guide, there are some recommendations for using enhanced text formatting for things like placeholders (both inline and in code blocks).

AsciiDoc provides pretty straightforward support for custom inline styles:

This command installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project.

But code blocks are a bit trickier, and will likely require appropriate substitutions depending on whether we decide to use roles or HTML passthrough.

When we temporarily pulled the global nav after launching the unified site on new AWS infrastructure, some users experienced UI issues like the top part of the page being cut off:

@mlr thinks this is likely the browser caching old styles, and that the usual way to mitigate this is asset file fingerprinting. However, we're not sure if that’s something Antora supports out of the box. We should investigate if asset file fingerprinting is a desirable and achievable solution to this problem, since we will be adding more rich UI experiences in the near future.

We currently set [source,cql] on code blocks containing CQL statements. However, since there is no CQL definition available for highlight.js, these code blocks have no syntax highlighting. (Note: we currently have issue #76 to develop a CQL definition ourselves.)

Until such time that a CQL definition becomes available, we should consider making cql an alias for the built-in sql definition in highlight.js. The languages are similar enough that if we applied SQL highlighting to CQL code blocks, the sacrifice in technical accuracy would probably be outweighed by the value users would gain by having at least rudimentary highlighting.

In the old UI, we provide manual controls for the following:

• Minimize or expand the entire left nav (more important of the two behaviors)
• Expand or collapse all nested items in the left nav

This feature was added at the request of a few internal users, and is something we should at least consider adding back to the new UI. The Astra Portal allows manual control to minimize/expand the left-nav, but the new docs UI only offers this control at smaller screen widths.

When inline monospace text (code text) snippets are on adjacent lines in the same paragraph, the "background box" overlaps. This most commonly occurs in tables where monospace text is more likely to wrap.

In Safari, the langchain-plus-ds-graphic.svg graphic doesn't show up on the new landing page:

After some brief investigation, it doesn't appear to be an issue with the SVG file. It also doesn't appear to be an issue with the Tailwind classes defined in the svg macro (removing them doesn't resolve the issue).

I suspect the issue lies further up in the divs, but haven't been able to confirm.

We should consider making some usability improvements to the in-page ToC (right-hand nav).

On width-constrained screens, we simply move the ToC to the top of the page. This means that if you land on a section in the middle of the page (either from xref or search) you won't even see the ToC, and using it requires you to scroll all the way back to the top. Also, since the ToC doesn't collapse, large ToCs take up a lot of real estate. We should consider better collapse behaviors that are more useful and take up less room.

We might also consider making visual improvements so that it's easier to identify which page section you're currently scrolling offer better support for third-level section headers.

Long monospace strings can break certain elements. Below I've provided examples of how this can break tables and horizontal description lists, but there may be more cases that I haven't discovered yet.

Tables

Example AsciiDoc:

[cols="2,3"]
|===
| Metric | Description

| `astra_db_rate_limited_requests:rate1m` and `astra_db_rate_limited_requests:rate5m`
| A calculated rate of change for the number of failed operations due to an {astra_db} xref:databases:database-limits.adoc[rate limit].
Using these rates, alert if the value is greater than 0.

| `astra_db_read_requests_failures:rate1m` and `astra_db_read_requests_failures:rate5m`
| A calculated rate of change for the number of failed reads.
Cassandra drivers retry failed operations, but significant failures can be problematic.
Using these rates, alert if the value is greater than 0.
Warn alert on low amount.
High alert on larger amounts; determine potentially as a percentage of read throughput.

| `astra_db_read_requests_timeouts:rate1m` and `astra_db_read_requests_timeouts:rate5m`
| A calculated rate of change for read timeouts.
Timeouts happen when operations against the database take longer than the server side timeout.
Using these rates, alert if the value is greater than 0.

| `astra_db_read_requests_unavailables:rate1m` and `astra_db_read_requests_unavailables:rate5m`
| A calculated rate of change for reads where service is not available to complete a specific request.
Using these rates, alert if the value is greater than 0.

| `astra_db_write_requests_failures:rate1m` and `astra_db_write_requests_failures:rate5m`
| A calculated rate of change for the number of failed writes.
Cassandra drivers retry failed operations, but significant failures can be problematic.
Using these rates, alert if the value is greater than 0.
Warn alert on low amount.
High alert on larger amounts; determine potentially as a percentage of read throughput.

| `astra_db_write_requests_timeouts:rate1m` and `astra_db_write_requests_timeouts:rate5m`
| A calculated rate of change for timeouts, which occur when operations take longer than the server side timeout.
Using these rates, compare with write_requests_failures.

| `astra_db_write_requests_unavailables:rate1m` and `astra_db_write_requests_unavailables:rate5m`
| A calculated rate of change for unavailable errors, which occur when the service is not available to service a particular request.
Using these rates, compare with write_requests_failures.

| `astra_db_range_requests_failures:rate1m` and `astra_db_range_requests_failures:rate5m`
| A calculated rate of change for the number of range reads that failed.
Cassandra drivers retry failed operations, but significant failures can be problematic.
Using these rates, alert if the value is greater than 0.
Warn alert on low amount.
High alert on larger amounts; determine potentially as a percentage of read throughput.

| `astra_db_range_requests_timeouts:rate1m` and `astra_db_range_requests_timeouts:rate5m`
| A calculated rate of change for timeouts, which are a subset of total failures.
Use this metric to understand if failures are due to timeouts.
Using these rates, compare with range_requests_failures.

| `astra_db_range_requests_unavailables:rate1m` and `astra_db_range_requests_unavailables:rate5m`
| A calculated rate of change for unavailable errors, which are a subset of total failures.
Use this metric to understand if failures are due to timeouts.
Using these rates, compare with range_requests_failures.

| `astra_db_write_latency_seconds:rate1m` and `astra_db_write_latency_seconds:rate5m`
| A calculated rate of change for write throughput.
Alert based on your application Service Level Objective (business requirement).

| `astra_db_write_latency_seconds_P$QUANTILE:rate1m` and `astra_db_write_latency_seconds_P$QUANTILE:rate5m`
| A calculated rate of change for write latency, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50 (e.g. `astra_db_write_latency_seconds_P99:rate1m`).
Alert based on your application Service Level Objective (business requirement).

| `astra_db_write_requests_mutation_size_bytesP$QUANTILE:rate1m` and `astra_db_write_requests_mutation_size_bytesP$QUANTILE:rate5m`
| A calculated rate of change for how big writes are over time, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50.
For example, `astra_db_write_requests_mutation_size_bytesP99:rate5m`.

| `astra_db_read_latency_seconds:rate1m` and `astra_db_read_latency_seconds:rate5m`
| A calculated rate of change for read latency.
Alert based on your application Service Level Objective (business requirement).

| `astra_db_read_latency_secondsP$QUANTILE:rate1m` and `astra_db_read_latency_secondsP$QUANTILE:rate5m`
| A calculated rate of change read latency, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50. For example, `astra_db_read_latency_secondsP99:rate1m`.
Alert based on your application Service Level Objective (business requirement).

| `astra_db_range_latency_seconds:rate1m` and `astra_db_range_latency_seconds:rate5m`
| A calculated rate of change for range read throughput.
Alert based on your application Service Level Objective (business requirement).

| `astra_db_range_latency_secondsP$QUANTILE:rate1m` and `astra_db_range_latency_secondsP$QUANTILE:rate5m`
| A calculated rate of change of range read for latency, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50. For example, `astra_db_range_latency_secondsP99`.
Alert based on your application Service Level Objective (business requirement).
|===

Horizontal description lists

NOTE: You'll notice that monospace appears with incorrect formatting when in a description list. This is either the same or similar to one of the issues being fixed in #103.

Example AsciiDoc:

[horizontal]
`astra_db_rate_limited_requests:rate1m` and `astra_db_rate_limited_requests:rate5m`::
A calculated rate of change for the number of failed operations due to an {astra_db} xref:databases:database-limits.adoc[rate limit].
Using these rates, alert if the value is greater than 0.

`astra_db_read_requests_failures:rate1m` and `astra_db_read_requests_failures:rate5m`::
A calculated rate of change for the number of failed reads.
Cassandra drivers retry failed operations, but significant failures can be problematic.
Using these rates, alert if the value is greater than 0.
Warn alert on low amount.
High alert on larger amounts; determine potentially as a percentage of read throughput.

`astra_db_read_requests_timeouts:rate1m` and `astra_db_read_requests_timeouts:rate5m`::
A calculated rate of change for read timeouts.
Timeouts happen when operations against the database take longer than the server side timeout.
Using these rates, alert if the value is greater than 0.

`astra_db_read_requests_unavailables:rate1m` and `astra_db_read_requests_unavailables:rate5m`::
A calculated rate of change for reads where service is not available to complete a specific request.
Using these rates, alert if the value is greater than 0.

`astra_db_write_requests_failures:rate1m` and `astra_db_write_requests_failures:rate5m`::
A calculated rate of change for the number of failed writes.
Cassandra drivers retry failed operations, but significant failures can be problematic.
Using these rates, alert if the value is greater than 0.
Warn alert on low amount.
High alert on larger amounts; determine potentially as a percentage of read throughput.

`astra_db_write_requests_timeouts:rate1m` and `astra_db_write_requests_timeouts:rate5m`::
A calculated rate of change for timeouts, which occur when operations take longer than the server side timeout.
Using these rates, compare with write_requests_failures.

`astra_db_write_requests_unavailables:rate1m` and `astra_db_write_requests_unavailables:rate5m`::
A calculated rate of change for unavailable errors, which occur when the service is not available to service a particular request.
Using these rates, compare with write_requests_failures.

`astra_db_range_requests_failures:rate1m` and `astra_db_range_requests_failures:rate5m`::
A calculated rate of change for the number of range reads that failed.
Cassandra drivers retry failed operations, but significant failures can be problematic.
Using these rates, alert if the value is greater than 0.
Warn alert on low amount.
High alert on larger amounts; determine potentially as a percentage of read throughput.

`astra_db_range_requests_timeouts:rate1m` and `astra_db_range_requests_timeouts:rate5m`::
A calculated rate of change for timeouts, which are a subset of total failures.
Use this metric to understand if failures are due to timeouts.
Using these rates, compare with range_requests_failures.

`astra_db_range_requests_unavailables:rate1m` and `astra_db_range_requests_unavailables:rate5m`::
A calculated rate of change for unavailable errors, which are a subset of total failures.
Use this metric to understand if failures are due to timeouts.
Using these rates, compare with range_requests_failures.

`astra_db_write_latency_seconds:rate1m` and `astra_db_write_latency_seconds:rate5m`::
A calculated rate of change for write throughput.
Alert based on your application Service Level Objective (business requirement).

`astra_db_write_latency_seconds_P$QUANTILE:rate1m` and `astra_db_write_latency_seconds_P$QUANTILE:rate5m`::
A calculated rate of change for write latency, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50 (e.g. `astra_db_write_latency_seconds_P99:rate1m`).
Alert based on your application Service Level Objective (business requirement).

`astra_db_write_requests_mutation_size_bytesP$QUANTILE:rate1m` and `astra_db_write_requests_mutation_size_bytesP$QUANTILE:rate5m`::
A calculated rate of change for how big writes are over time, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50.
For example, `astra_db_write_requests_mutation_size_bytesP99:rate5m`.

`astra_db_read_latency_seconds:rate1m` and `astra_db_read_latency_seconds:rate5m`::
A calculated rate of change for read latency.
Alert based on your application Service Level Objective (business requirement).

`astra_db_read_latency_secondsP$QUANTILE:rate1m` and `astra_db_read_latency_secondsP$QUANTILE:rate5m`::
A calculated rate of change read latency, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50. For example, `astra_db_read_latency_secondsP99:rate1m`.
Alert based on your application Service Level Objective (business requirement).

`astra_db_range_latency_seconds:rate1m` and `astra_db_range_latency_seconds:rate5m`::
A calculated rate of change for range read throughput.
Alert based on your application Service Level Objective (business requirement).

`astra_db_range_latency_secondsP$QUANTILE:rate1m` and `astra_db_range_latency_secondsP$QUANTILE:rate5m`::
A calculated rate of change of range read for latency, where $QUANTILE is a histogram quantile of 99, 95, 90, 75, or 50. For example, `astra_db_range_latency_secondsP99`.
Alert based on your application Service Level Objective (business requirement).

We generally scale down all elements within a table (e.g. smaller font/symbol size) to mitigate the inherent space constraints. However, admonitions (and their contents) don't appear to follow the same scaling factor, and seem to render just as they do when outside of a table. See the complex table example in the UI preview: https://riptano.github.io/docs-ui/main/asciidoc/tables.html#complex-table-w-asciidoc-content

IMO we should probably scale down at least the content of an admonition when it appears in a table. But perhaps we should scale down other aspects like the label/symbol and the top color bar.

Headings in the left nav have expand/collapse functionality and default to collapsed state on page load. Sub-headings should behave the same way. However, currently, you can't expand/collapse sub-headings at all, and they default to open.

For example, see the sub-headings in the Databases section: