How to install Wagtail Code Block for Wagtail 4?

For Wagtail 4.0 and greater, run 'pip install wagtailcodeblock' and add 'wagtailcodeblock' to INSTALLED_APPS. For older Wagtail versions, use specific versions like 1.28.0.0 for Wagtail 3.x, as detailed in the README.

Wagtail Code Block vs other Wagtail syntax highlighting plugins?

Wagtail Code Block offers real-time admin highlighting and built-in features like line numbers and copy buttons using PrismJS. Alternatives might be more lightweight or use different highlighters, but this plugin is best for seamless PrismJS integration out-of-the-box.

How to change the theme in Wagtail Code Block?

Set the WAGTAIL_CODE_BLOCK_THEME in Django settings to a PrismJS theme like 'dark', 'okaidia', or 'solarizedlight'. The default is 'coy', which is chosen to match Wagtail's admin interface design.

Does Wagtail Code Block support custom languages?

Yes, you can customize the languages by modifying the WAGTAIL_CODE_BLOCK_LANGUAGES setting in Django. The README provides a full list of PrismJS language codes to include or exclude based on your needs.

How to disable line numbers in Wagtail Code Block?

Disable line numbers by setting WAGTAIL_CODE_BLOCK_LINE_NUMBERS = False in Django settings. Similarly, the copy button can be turned off with WAGTAIL_CODE_BLOCK_COPY_TO_CLIPBOARD = False.

Is Wagtail Code Block compatible with Wagtail's StreamField?

Yes, it's designed as a StreamField block and integrates seamlessly, as shown in the example usage where CodeBlock is added to a StreamField list for pages like HomePage.

Wagtail Code Block — Code Block for Wagtail CMS

What is Wagtail Code Block?

Wagtail Code Block is a Django/Wagtail extension that adds a StreamField block for displaying source code with syntax highlighting. It solves the problem of presenting code snippets in Wagtail-powered websites by providing real-time highlighting in both the admin interface and frontend using PrismJS. The package makes it easy for content editors to add properly formatted code without needing technical markup knowledge.

Target Audience

Wagtail CMS developers and content editors who need to display code snippets in their websites. It's particularly useful for technical documentation sites, educational platforms, and developer blogs built with Wagtail.

Value Proposition

Developers choose Wagtail Code Block because it provides seamless integration with Wagtail's StreamField system, requires minimal configuration, and offers consistent syntax highlighting across both admin and frontend interfaces. Unlike generic code display solutions, it's specifically designed for Wagtail's architecture and editor workflow.

StreamField code blocks for the Wagtail CMS with real-time PrismJS Syntax Highlighting.

Use Cases

Best For

Adding code snippets to Wagtail blog posts and articles
Creating technical documentation sites with Wagtail CMS
Building educational platforms that require code examples
Displaying API examples in developer documentation
Showing configuration examples in tutorials and guides
Presenting code samples in portfolio sites for developers

Not Ideal For

Projects not built with Wagtail CMS, as it's tightly integrated and won't work with other frameworks or standalone Django
Applications requiring syntax highlighting without JavaScript, since frontend rendering depends on PrismJS client-side execution
Teams needing to use a different syntax highlighting library like Highlight.js, due to hard-coded PrismJS integration
High-performance websites where minimizing JavaScript bundle size is critical, as PrismJS can add significant weight

Pros & Cons

Pros

Real-time Admin Highlighting

Provides immediate syntax highlighting in the Wagtail editor as content editors type, enhancing the editing experience without page reloads, as shown in the screenshot.

Frontend PrismJS Integration

Uses PrismJS to deliver consistent, beautifully formatted code on the frontend with support for multiple themes like Coy, Dark, and Okaidia, configurable via Django settings.

Built-in Usability Features

Includes line numbers and a copy-to-clipboard button by default, both configurable through settings like WAGTAIL_CODE_BLOCK_LINE_NUMBERS and WAGTAIL_CODE_BLOCK_COPY_TO_CLIPBOARD.

Extensive Language Support

Supports dozens of programming languages from Python to YAML, with a customizable language list via WAGTAIL_CODE_BLOCK_LANGUAGES, including esoteric options like Brainfuck and Zig.

Cons

PrismJS Lock-in

The project is hardcoded to use PrismJS, making it difficult to switch to alternative syntax highlighters without forking or significant customization, limiting flexibility.

Versioning Complexity

Version numbers are tied to PrismJS releases (e.g., 1.28.0.X), which can confuse dependency management and require careful matching with Wagtail versions, as noted in installation instructions.

JavaScript Dependency

Frontend highlighting relies on PrismJS JavaScript, so it won't work in environments with JS disabled or where server-side rendering is preferred for performance or accessibility.

Wagtail-Only Scope

Designed exclusively for Wagtail's StreamField, so it's unusable for projects outside Wagtail or those needing syntax highlighting in other parts of a Django app without Wagtail.

Frequently Asked Questions

What is Wagtail Code Block?

Target Audience

Value Proposition

Use Cases

Best For

Adding code snippets to Wagtail blog posts and articles
Creating technical documentation sites with Wagtail CMS
Building educational platforms that require code examples
Displaying API examples in developer documentation
Showing configuration examples in tutorials and guides
Presenting code samples in portfolio sites for developers

Not Ideal For

Projects not built with Wagtail CMS, as it's tightly integrated and won't work with other frameworks or standalone Django
Applications requiring syntax highlighting without JavaScript, since frontend rendering depends on PrismJS client-side execution
Teams needing to use a different syntax highlighting library like Highlight.js, due to hard-coded PrismJS integration
High-performance websites where minimizing JavaScript bundle size is critical, as PrismJS can add significant weight

Pros & Cons

Pros

Real-time Admin Highlighting

Provides immediate syntax highlighting in the Wagtail editor as content editors type, enhancing the editing experience without page reloads, as shown in the screenshot.

Frontend PrismJS Integration

Uses PrismJS to deliver consistent, beautifully formatted code on the frontend with support for multiple themes like Coy, Dark, and Okaidia, configurable via Django settings.

Built-in Usability Features

Includes line numbers and a copy-to-clipboard button by default, both configurable through settings like WAGTAIL_CODE_BLOCK_LINE_NUMBERS and WAGTAIL_CODE_BLOCK_COPY_TO_CLIPBOARD.

Extensive Language Support

Supports dozens of programming languages from Python to YAML, with a customizable language list via WAGTAIL_CODE_BLOCK_LANGUAGES, including esoteric options like Brainfuck and Zig.

Cons

PrismJS Lock-in

The project is hardcoded to use PrismJS, making it difficult to switch to alternative syntax highlighters without forking or significant customization, limiting flexibility.

Versioning Complexity

Version numbers are tied to PrismJS releases (e.g., 1.28.0.X), which can confuse dependency management and require careful matching with Wagtail versions, as noted in installation instructions.

JavaScript Dependency

Frontend highlighting relies on PrismJS JavaScript, so it won't work in environments with JS disabled or where server-side rendering is preferred for performance or accessibility.

Wagtail-Only Scope

Designed exclusively for Wagtail's StreamField, so it's unusable for projects outside Wagtail or those needing syntax highlighting in other parts of a Django app without Wagtail.

Frequently Asked Questions

Wagtail Code Block

What is Wagtail Code Block?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Wagtail Code Block

What is Wagtail Code Block?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?