Codeblock Styler Plugin

This is a plugin for Obsidian.md which lets you style codeblocks and inline code in both editing mode and reading mode.

Settings

Excluded Codeblocks

The plugin can be set to ignore certain codeblocks completely (for example if another plugin uses them like the dataview codeblocks). These are set in settings as a comma separated list. The wildcard * operator can also be used to match languages such as 'ad-*' to match admonitions.

This setting is used to tell the plugin which codeblocks it can ignore completely as opposed to just not decorating the codeblock. To not decorate a codeblock, use the excluded languages setting.

Note

Setting excluded codeblocks for codeblocks used by other plugins you use is important as otherwise, the plugin does not know which codeblocks to ignore in certain cases.

Excluded Languages

The plugin can be set to ignore certain languages (for example if you want python codeblocks to not be decorated). These are set in settings as a comma separated list. The wildcard * operator can also be used to match languages such as 'ad-*' to match admonitions.

This setting is used to tell the plugin to not decorate certain languages. To completely ignore a codeblock (i.e. a codeblock which doesn't generate a rendered codeblock in reading mode as a result of a plugin), use the excluded codeblocks setting.

Themes

The plugin comes with a 'Default' theme and a few themes based on popular colour schemes. The default theme uses colours as defined by the existing Obsidian theme to minimise changes in appearance on install (it uses the CSS variables defined by the current theme).

All themes have customisable colours for both light and dark mode (to make changes to a specific mode, change to that mode first and then change the colours in settings). Each theme also includes other appearance settings such as displaying line numbers, allowing highlights to cover the line numbers and more.

When a setting or colour is changed within a theme, that change is not saved to the theme; you must then click the update button next to the theme name to update that theme to the current settings. Note that changes to the built-in themes cannot be saved.

The different component colours that can be set within a theme are:

• Codeblock background colour
• Codeblock text colour
• Line number gutter background colour
• Line number text colour
• Codeblock line number current line indicator
• Codeblock header background colour
• Codeblock header title text colour
• Codeblock header separator colour
• Codeblock header language tag background colour
• Codeblock header language tag text colour
• Editor active line highlight colour
• Codeblock active line highlight colour
• Default highlight colour
• Alternative highlight colours
• Button colour
• Button active colour

'Default' theme colours in dark mode with Default Obsidian theme:

'Default' theme colours in light mode with Default Obsidian theme:

'Default' theme colours in dark mode with Obsidianite theme:

'Solarized' theme colours in dark mode with Default Obsidian theme:

I am not a designer, so if you have created a cool theme, send me the colour codes, and I might include it as a default theme in the next release :-)

Codeblock Parameters

Codeblock parameters are added to the first line of the codeblock following the language. They can be added in any order. If no language is set, a space should be left after the codeblock delimiter ``` to indicate that the first parameter is NOT the language of the codeblock.

Example:

• ```cpp fold title:example_title
• ```cpp title:example_title fold (same effect as above line)
• ``` fold title:example_title (if no language set)

Line Numbers

Line numbers can be enabled/disabled within a specific theme in the settings of that theme. In addition to this, whether line numbering is applied can be additionally specified in a codeblock itself using the ln parameter.

Setting ln:true will always show line numbering, ln:false will never show line numbering, and ln:NUMBER (e.g.ln:27) will always show line numbering starting at the specified number (so an offset of this number minus one).

Title

To display a title for a codeblock specify title: followed by a title in the first line of the codeblock. If the title contains spaces, specify it between "" or '' e.g.: title:"long filename.cpp".

Example:

```cpp title:test.cpp

```cpp title:"long filename.cpp"

Folding

To specify an initial fold state when the document is opened, use the fold parameter. If fold is set in a codeblock, then when you open the document, the codeblock will be automatically collapsed, and only the header will be displayed. You can unfold the codeblock by clicking on the header.

Clicking on any header will toggle the fold for that codeblock.

When no title parameter is set, the folded codeblock will have a default fold placeholder title. This can be changed in settings, or it can be changed for a specific parameter by setting a string after the fold parameter as in fold:Folded or fold:"Collapsed Codeblock".

Example:

```cpp fold

```cpp fold:"This is collapsed"

Clicking on header

Highlighting

To highlight lines, specify hl: followed by line numbers, plain text or regular expressions in the first line of the codeblock.

You can specify any of the following highlight types separated with commas (without spaces) e.g.: hl:1,3-4,foo,'bar baz',"bar and baz",/#\w{6}/.

• Single numbers: hl:1 would highlight the first line
• Number ranges: hl:1-3 would highlight lines 1 through to 3
• Plain text: hl:foo would highlight lines with the word foo inside them
• Plain text in speech marks or quotation marks: hl:'bar baz' or hl:"bar baz" would highlight lines with the word bar baz inside them
• Regular Expressions: hl:/#\w{6}/ would highlight lines which match this regular expression (tested by regex.test(line)) - for this example any lines with hexadecimal colours are highlighted

Combinations of these will highlight all relevant lines.

Example: ```cpp hl:1,3-4,foo,'bar baz',"bar and baz",/#\w{6}/

Highlights can be set to also highlight line numbers as well as the code in settings.

Example:

Highlights created by the default highlight parameter or alternative highlight parameters can be set to appear as gradient highlights which fade out to the right in the settings. A colour stop percentage for this gradient can also be set.

Example:

Alternative Highlights

You can also define multiple highlight colours by defining an alternative highlight colour with a name. This name will be used as a parameter, and you can use it just like with the hl parameter.

Example:

You could add three further types of highlight colours (info, warn, error). After adding these in settings and setting colours as desired, you can use it in the first line of codeblocks:

```cpp info:2 warn:4-6 error:8

Corresponding settings:

Unwrap

Whether lines wrap or note can be set in the settings. There is an advanced option called "Wrap Lines on Click" where holding the mouse down on a codeblock's content will cause the content to be wrapped (if line unwrapping is already set in the settings).

These settings can also be set on a per codeblock basis using the unwrap parameter which overrides the settings. Setting unwrap:true will unwrap lines in the codeblock, setting unwrap:false will wrap lines in the codeblock, and setting unwrap:inactive will unwrap lines in the codeblock but will wrap them when the mouse is held down on the codeblock.

Example:

```python unwrap:true

```python unwrap:false

```python unwrap:inactive

Ignore

In addition to excluding the language, the plugin can be told to not apply to a specific codeblock by including the ignore parameter.

The plugin can further be told to not apply to a specific file by adding code-styler-ignore: true to the frontmatter of the note.

Example:

```cpp ignore

code-styler-ignore: true

Appearance

Codeblock

Codeblocks can have their curvature changed in settings to make them appear more or less rounded.

They can also have coloured left borders based on the language (colours match the language icon) if enabled in settings. The width of this border can also be changed.

Example:

Header

The header is displayed in the following cases:

• You specified a title:
• You specified fold If you specified fold but did not specify title: or fold: a default text from settings will be displayed on the header (the default is 'Collapsed Code')
• You defined a codeblock language via ```language and set the Display Header Language Tags setting to Always or the Display Header Language Icons setting to Always in the theme settings

If the header is displayed, folding works as well. If the Display Header Language Tags setting is set to Always, then the header will display the codeblock language always and if it is set to If Header Shown, it will only display when the header is displayed (i.e. the title parameter is set).

You can enable the option in the settings page to display icons in the header. When this option is set to If Header Shown, if the language specified in the codeblock has an icon and the codeblock header is displayed (i.e. the title parameter is set), then the icon will be displayed. When this option is set to Always, the header with icon will always be shown if the language specified in the codeblock has an icon. Icons can also be set to grayscale or resized in settings. There are currently around 170 icons available for different languages.

The language tag text and title text can also be styled to be bold and/or italic as well as a specific font. Furthermore, the font-size of the header text can be changed.

Example:

• No header

• Header with fold only

• Header with codeblock language only

• Header with codeblock language and title as well

• Header with codeblock language, title and icon as well

Active Line Indicators

The active line inside codeblocks can be highlighted with a custom colour if enabled in settings. It can also be indicated by a different colour line number if this setting is also enabled in settings.

The active line outside codeblocks can also be highlighted with a custom colour if enabled in settings.

Example:

Inline Code

Inline code can be customised

Plugin Compatibility

This plugin is also compatible with the following obsidian plugins out of the box:

Roadmap

Take a look at the changelog to see what has changed in past versions.

Future Work

• Features to add:
  • Commands to fold all, unfold all and reset default fold for codeblocks .
    • Hook into existing fold commands as well.
  • Optional outer border.
  • Optional shadow for codeblock.
  • Dataview compatibility.
  • Compatibility with codeblocks created by indentation.
  • New Themes
    • Nord
    • Dracula
    • Gruvbox
    • Catpuccin
• Check the feasibility of:
  • Implementing code wrapping for editing mode.
  • Implementing folding animations for editing mode.
  • Make list codeblocks appear indented properly in reading mode.

Existing Issues

• General
  1. Indented codeblocks are not dealt with properly.
• Editing Mode
  1. On open of a note, there can be small differences in the line number margins.
  2. If a language is excluded or ignored, it currently needs to be unfolded before it can be removed or it disappears.
  3. Moving the cursor next to a collapsed codeblock and typing can cause it to disappear.
  4. Folding empty codeblocks causes the HyperMD-codeblock-end class and HyperMD-codeblock class not to be applied when unfolded.
• Reading Mode
  1. Codeblocks constantly collapse and re-expand if editing side by side in editing mode.
  2. Selecting codeblocks, copying and then pasting in reading mode includes line numbers and header titles and header icons.
  3. Docstring syntax highlighting issue.
• PDF Exporting
  1. Sometimes page breaks cut lines in half.
• iOS
  1. Numerous small UI issues
     • Header isn't the right size in editing mode.
     • Collapsed indicator not centred in reading mode

Upstream Issues

• Instant reading mode updating when parameters are changed
  • Requires Obsidian to parse postMarkdown changes following the codeblock language (see this issue and this issue).
• run-* codeblocks from the Execute Code Plugin in editing mode do not get changed
  • Requires the correct context source path to be returned. See this pull request.
• Parsing of line number margin width is not precise.
  • Due to delay in reading accurate information from DOM in codemirror, the current implementation is the most efficient approach. See here.
• The line numbers can flicker on collapse if highlighted for devices with high DPI screens due to a bug with position: sticky.
  • See this issue.

How to install the plugin

• Simply install directly from Obsidian
• Alternatively you can just copy over main.js, styles.css, manifest.json to your vault VaultFolder/.obsidian/plugins/code-styler/ or use the Obsidian Beta Reviewers Plugin.

Contributions

All contributions are welcome, just create a merge request. The bullet points in roadmap are a good place to start!

Please try to create bug reports/issues that are:

• Reproducible: Include steps to recreate the issue
• Specific: Include relevant details such as possible plugin conflicts, theme conflicts etc.
• Unique: Please do not duplicate existing open issues, add to the existing issue
• Scoped: Please create a separate issue for each bug you've identified

Maintainers

• @mayurankv

Contributors

Made with contrib.rocks.

This plugin is based on the Codeblock Customizer Plugin by @mugiwara85.

Support

If you like this plugin, and would like to help support continued development, use the button below!

License

Distributed under the MIT License. See LICENSE for more information.