[DISCUSSION] Custom text formatting and code snippet placeholders

[eric-schneider]

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.

[djsauble]

Here's one approach we could take: https://github.com/riptano/astra-vector-docs/pull/265

[djsauble]

https://github.com/riptano/astra-vector-docs/pull/265#pullrequestreview-1876576804

@kurtenj @colegoldsmith wdyt?

[polandll]

I'll add this item to this issue:

I see that you have a PR (https://github.com/riptano/astra-vector-docs/pull/265) to add bold to placeholders in source codeblocks. I’m guessing you do something in the antora ui to accomodate this? I’m asking, because I have a need to use italics in source codeblocks that are [source, bash], a similar issue. This would allow both bash highlighting AND italicized optional parameters to be displayed on those codeblocks. Right now, I have to pick one or the other, and Jamie and I have been looking at the google developers style guide, where they use the italicized parameters for optional params, and normal font for required params.

[eric-schneider]

@polandll What you're describing doesn't appear to be an issue in the new UI.

I ran the following test:

[source,sql,subs="verbatim,quotes"]
----
CREATE TABLE smart_home.sensor_readings (
    _device_id_ UUID,
    room_id UUID,
    reading_type TEXT,
    reading_value DOUBLE,
    reading_timestamp TIMESTAMP,
    PRIMARY KEY (device_id, room_id, reading_timestamp)
) WITH CLUSTERING ORDER BY (room_id ASC, reading_timestamp DESC);
----