Adding a code block or code snippet in Confluence is relatively quick and easy. When writing technical documentation, it’s helpful to include code examples to provide meaningful context to the reader.
For example, you might want to show how a global variable is set and used throughout a particular flow in your code. Inserting a code block is the best way to illustrate the what, how, and why of doing that.
There are several ways to add code to your Confluence docs. This is part of our series of articles about Atlassian Confluence.
What are Confluence macros?
Confluence macros are extensions to the native functionality of Confluence pages. When editing a document, macros are available via the “+” menu in the toolbar. Popular built-in macros include Attachments, Google Drive, and the Table of Contents macro.
Macros can be written using HTML, proprietary XML tags, or the Java-based template engine, Apache Velocity. They function like small applications that can accept parameters and change functionality based on those parameters.
Macros can be repackaged into plugins, which include code bundles, resources, and configuration files that can either create new functionality or manipulate existing functionality within Confluence.
What is the Confluence code block macro?
The code block macro allows you to write or paste code directly into your Confluence pages. Pages published with code snippets have the look and feel of a native IDE, including proper syntax highlighting, indentation, and presentation elements that can be customized with CSS.
Code blocks are a great way to provide context to readers and demonstrate using either hypothetical or real-world code fragments. Developers learn best when they can glean context from code and implementation details.
We believe context is king and that code is as much about the sum of the parts as it is about the parts themselves. Pairing code directly with the documentation provides understanding beyond variables and classes, which is why the code block macro is a Confluence feature worth talking about.
The code block macro goes beyond source code. It can also be used to display command line interface actions and detailed logs from applications and services. Various parameters can be used with the code block macro, including selecting the appropriate programming language, showing line numbers, and more.
Writing user macros
Confluence can be extended with custom user macros beyond those provided by Atlassian. Macros allow you to manipulate the formatting of your docs and add custom functionality. User macros are built with custom code directly within the Confluence web app. They can be written and managed only by users with administrative privileges.
User macro access can be scoped for individual users or shared across the entire platform. They have a standardized template syntax to make them easy to use once they’re implemented.
How to insert the code block macro in your page
Confluence’s page editor makes it easy to insert various types of content blocks, including a code snippet . Once you are in the edit mode for a page, you can click the “+” icon in the toolbar and select “Code snippet.”
You can also use a forward slash shortcut (or “slash command”) to trigger the in-editor context menu. Simply type: /code in your doc and you’ll see the “Code snippet” option pop up.
The code block macro can also be added with wiki markup syntax, like the following:
{code:title=Document Title|theme=Emacs|linenumbers=true|language=YAML}
code-coupled-documentation: “Yes, please!”
{code}
Select the programming language for syntax highlighting
Once you’ve added the snippet, you’ll be presented with a code editor directly in your Confluence document, which includes line numbers and a dropdown menu allowing you to select a programming language for appropriate syntax highlighting. You can see all the languages available in the official Confluence documentation.
Adjust the visual width of the code snippet editor
In the upper-right corner of the code snippet editor is an icon that lets you widen the visual editor. Confluence calls this the “Go wide” button. Clicking it gives you the option of the default text column width, a slightly expanded view, or a full-page width. Obviously, which view you prefer is a matter of preference and has no bearing on the function of the code snippet.
Add code to the snippet editor
Add code in the snippet editor by typing or pasting. It’s important to note that you won’t see syntax highlighting take effect until after you’ve clicked Publish or Update. The published reading version of the page will have the appropriate syntax coloring and highlighting.
Advanced: customize the appearance of code snippets with CSS
Confluence allows developers and administrators to customize the look and feel of the application and the pages you create. You can update the CSS stylesheets and make your pages and code snippets look exactly how you like. Here’s the official documentation on giving Confluence a makeover. (Note: you might need to be a Confluence administrator to access this function, depending on how your Confluence instance is configured.)
You can also try adding custom CSS to the page header via the “Space Settings” gear icon sidebar. Navigate to the “Look and Feel” tab and then to the “Header and Footer” tab.
How to add code blocks with Swimm
We have written extensively about code-coupled documentation and have built an entire application ecosystem to help developers include live code – using code snippets – in their documentation.
Confluence’s code block and editor are great tools, but they contribute to the problem of docs being outdated as soon as they’re published.
Swimm has a much better way of including living code in docs and connecting the documentation directly with the code. Use our slash commands to include code snippets directly from the code repository itself. No “copypasta.” Just highlight the code you want to include and start writing a doc.
We swear it’s really that easy!
Bottom line
Swimm integrates directly with popular IDE plugins, including VS Code and IntelliJ, so developers know when docs are available for the code they’re reading or changing. We integrate directly with CI/CD pipelines, and our AI/ML engine can notify developers via Slack and Swimm’s GitHub app of critical documentation-related updates.
Additionally, Swimm docs live alongside the code in the code repository. Swimm makes sure the docs are updated automatically when the code changes.
We call this Continuous Documentation, an innovation that enables dev teams to easily create documentation that’s always up to date and easy to find the moment you need it. It’s designed to meet the very real documentation challenges and needs of dev around the world.
Want to give it a try? Sign up for free to see what code-coupled, always up-to-date documentation looks like.
