Using Code Snippets in Confluence

[#1]

As someone who frequently documents Python and Bash scripts in Confluence, I've come to really appreciate the Code Snippet element in the new editor.

It makes technical documentation so much cleaner and more readable.

After using it extensively for my own runbooks and automation scripts, I thought I'd share some practical tips and best practices that might help others get the most out of this feature.

What is the Code Snippet Element?

The Code Snippet is a Basic Element in the new Confluence editor that displays code with syntax highlighting.

Perfect for:

• 📚 Technical documentation
• 🔧 API guides
• 📝 Runbooks & troubleshooting guides
• 💡 How-to articles for developers
  
  
  

4 Ways to Insert

1. Via Slash Menu (Fastest Method)

1. Type /code on a new line
2. Select "Code snippet" from the list
3. Paste your code

2. Via Toolbar

1. Click the + symbol in the toolbar
2. Select "Code snippet" under "Basic elements"

3. Via Drag & Drop

1. Open the element panel (left side)
2. Drag "Code snippet" onto the page

4. Keyboard Shortcut ⌨️

• Select text → Ctrl/Cmd + Shift + M
• Converts text directly into a Code Snippet

Supported Programming Languages

The Code Snippet element supports syntax highlighting for many languages:

Backend:

• Python, Java, C#, C++, Go, Ruby, PHP, Rust

Frontend:

• JavaScript, TypeScript, HTML, CSS, React (JSX)

DevOps & Scripting:

• Shell, PowerShell, YAML, JSON, XML, SQL

Others:

• Markdown, Dockerfile, Terraform, GraphQL

💡 Tip: The language is often detected automatically. However, you can also set it manually via the dropdown menu in the code block.

Best Practices for Technical Documentation

✅ DO's

1. Set Language Explicitly

2. Short, Focused Snippets

• Max. 20-30 lines per snippet
• Split longer code into multiple blocks
• Add a heading to each block

3. Add Context

Always add a brief explanation BEFORE the code.

4. Use Line Numbers

• Enable line numbers for longer snippets
• Makes referencing easier in reviews

❌ DON'Ts

• ❌ No sensitive data (API keys, passwords)
• ❌ No huge code dumps (> 50 lines)
• ❌ No outdated code examples without version number

Practical Use Cases

1. API Documentation

Example: REST API Endpoint

Response

2. Runbooks & Troubleshooting

Problem: Service won't start

Solution:

3. Configuration Examples

Docker Compose Setup:

Tips for Developer Teams

📌 Mention Versioning

Always specify which version the code is for:

ℹ️ Note: This code works with Python 3.9+

🔗 Link to Sources

Link to official documentation:

• Python Docs
• MDN Web Docs

🎯 Inline Comments

Use comments for explanations:

Avoiding Common Mistakes

Problem 1: Code isn't formatted

Solution: Make sure you're using the Code Snippet element, not normal text with monospace font.

Problem 2: Syntax highlighting missing

Solution: Select the language manually from the dropdown menu.

Problem 3: Code is too wide

Solution:

• Use shorter variable names
• Break long lines
• Enable horizontal scrolling

Keyboard Shortcuts for Power Users

Action	Shortcut
Insert Code Snippet	/code
Convert text to code	Ctrl/Cmd + Shift + M
Change language	Click dropdown in block
Copy code	Hover → Copy button

Integration in Workflows

Document Code Reviews

1. Code Snippet with review comments
2. Add status label (✅ Approved, ⚠️ Needs Changes)
3. @mention the developer

Maintain Changelog

Summary

✅ Code Snippet Element = Professional code presentation
✅ Syntax highlighting for 20+ languages
✅ Perfect for API docs, runbooks, how-tos
✅ Keyboard shortcuts save time

Are you already using Code Snippets? Share your tips in the comments!

---

Sources

• Add elements to a page - Atlassian Support
• Confluence Cloud Documentation