Change Background of inline code statements (backticks)

[Blackjacx]

Feature Name

Visibility of Inline Code Statements

Description

Hey ✌️

I wondered if it is possible to change the background of inline code statements to lets say gray like the GitHub style markdown is doing it. I was not able to find a DocC Website that has this :-(

I'm building my own and inline code is not very legible...

Motivation

Visibility of Inline Code Statements and my own DocC based "website". I use it as static site generator what works amazingly well.

Importance

No response

Alternatives Considered

No response

[d-ronnqvist]

Does someone know if the code background already is configurable?

There are examples in the appearance customization documentation with custom background colors for the code blocks but I don't know if that's individually configurable.

[Blackjacx]

Actually I'm setting these custom fill colors already (here), Effect can be seen here but the inline code statements are not affected.

[mportiz08]

Very cool theme @Blackjacx!

From the provided links, I'm seeing that you have specified a color override which is being used for the code listing background, although maybe it was unexpected.

The color for the code listing background can be specified using the --code-color-background variable which should apply to all inline code listings.

By default (without overriding it), this value maps to another color variable called --color-fill-secondary. In your case, this color has been overwritten, so this value is being used by code listings.

So, you have 2 options to change this:

1. Use an alternate color for --color-fill-secondary in your theme settings—this would apply to other places and not just code.
2. Override --color-code-background in your theme settings, which should only apply to code listings.

Hope this helps! The theme you've created looks great so far to me.

[mportiz08]

(It sounds like option 2 might be what you're looking for)

[Blackjacx]

Uhh thanks for reaching out so quickly 👍 I'll try that asap!

[Blackjacx]

Also another related question:

How to get actual syntax highlighting in code blocks? At the moment htis looks a bit sad when using the following block with shell or bash

xyz

Then on the website it renders as follows:

[mportiz08]

Also another related question:

How to get actual syntax highlighting in code blocks? At the moment htis looks a bit sad when using the following block with shell or bash

xyz

Then on the website it renders as follows:

I would suggest contributing enhancements to highlight.js for the way that it tokenizes shell syntax, which is the npm package that we utilize for syntax highlighting purposes. Then we can pick up those enhancements here in Swift-DocC-Render while also benefiting the open source community in general.

I think it's pretty common for default shells on many systems to not syntax highlight different parts of command invocations, but I agree that it would be really great if there was a distinguishing colors for executables and arguments as one small example (like my preferred choice of shell does). It's probably not super trivial to make this kind of highlighting work in a way that is compatible with many/most shells though (bash/fish/zsh/etc), since I believe the highlight.js language is shell-agnostic and the syntax may differ between them.

[Blackjacx]

Hey there,

thanks for the quick reply. We will see what we can do here 👍

As a quick fix we was that Swift syntax highlighting works quite well:

• https://wwdcnotes.com/documentation/wwdcnotes/wwdc23-10146-meet-core-location-for-spatial-computing
• https://github.com/WWDCNotes/WWDCNotes/blob/43d01b138308a16107f6895f3c57153eeab326b9/Sources/WWDCNotes/WWDCNotes.docc/WWDC23/WWDC23-10146-Meet-Core-Location-for-spatial-computing.md?plain=1#L24C4-L24C9

Our question today was:

Is there a documentation which syntax highlightings in markdown 
code blocks are currently supported?

[d-ronnqvist]

Is there a documentation which syntax highlightings in markdown
code blocks are currently supported?

The Add Code Listings sections in the Swift-DocC documentation about formatting has a table that list the language identifiers that the renderer currently supports syntax highlighting for.

[Blackjacx]

@d-ronnqvist thank so much! You link helped to check out how the various language IDs behave 👍

@mportiz08 sorry that I come back so late but how do I exactly override --color-code-background in my theme settings? Sorry I'm not a big pro in web development and CSS 😅 I also could not find any documentation for this parameter - where does it come from actually? Is it CSS or does it come from DocC itself?

[mportiz08]

@d-ronnqvist thank so much! You link helped to check out how the various language IDs behave 👍

@mportiz08 sorry that I come back so late but how do I exactly override --color-code-background in my theme settings? Sorry I'm not a big pro in web development and CSS 😅 I also could not find any documentation for this parameter - where does it come from actually? Is it CSS or does it come from DocC itself?

No problem. The documentation for that file is here and the specific setting I mentioned is this one.

Within your theme-settings.json file, there is a "color" section, and you could provide a new key "code-background" along with a CSS color value(s) to override it with if you'd like—similar to the other color overrides within that file.

[Blackjacx]

Thanks for the links! Highly appreciated. I tested code-background and it only seems to apply for code blocks (top) but not for inline code (bottom) - the bg color is still transparent:

In the theme specs I could not find anything that may alter the incline code background.

Do you have any other idea?

[mportiz08]

Thanks for the links! Highly appreciated. I tested code-background and it only seems to apply for code blocks (top) but not for inline code (bottom) - the bg color is still transparent:

Yes, swift-docc-render only applies a colored background to block-level code listings by default.

In the theme specs I could not find anything that may alter the incline code background.

Do you have any other idea?

I think the only way to make this work would be to implement support for it in swift-docc-render. I don't know that we would want to introduce a background color for inline code by default, but we would be happy to take a contribution that makes it possible to opt-in to an inline code background color using theme-settings.

[Blackjacx]

I would love to contribute but this project is way too complex for me to do a "quick contribution". Sadly I can't dedicate that much time anymore to open source…

I could try to do it with a little bit of help from you guys. Just need a little hint to get started. For the beginning, where to find the call site / usage of the colors, like e.g. code-background.

[mportiz08]

I totally understand. Unfortunately I don't have the time to look into this myself at the moment, but here is the likely high level approach for anyone reading this that wants to try tackling this:

1. Find where the CodeVoice component is used within ContentNode.vue to map code formatting to the appropriate rendering and consider adding a new class to this component to indicate inline code (unfortunately this can't just be done in CodeVoice itself since it is used in other places like declarations where additional formatting might not make sense)
2. Add a new CSS style for this class that utilizes a new CSS variable like --color-inline-code-background (maybe a transparent default or something) to set the bg color
3. Update the ThemeSettings JSON schema in swift-docc to document the new theme variable as distinct/related PR

After that, developers can use theme-settings.json in a documentation catalog to set a unique color for these inline code elements for docs using that new var (when using a toolchain with latest Swift-DocC and Swift-DocC-Render after both PRs are merged)