Discourse Contribution Style Guide

Welcome Specify Members
1

Style Guide for Discourse Contributors

This style guide is exclusively for contributors to the Specify Community Forum (the site you are on now)!

Content Philosophy

  • Be professional and respectful—focus critiques on ideas, use inclusive language, and foster kindness.
  • Ensure accuracy—test advice before posting, cite reliable sources, and correct errors promptly.
  • Avoid duplication—search before posting and link to existing threads or documentation as the single source of truth.
  • Write clearly—use descriptive titles, format with headings or lists, and include minimal reproducible examples.
  • Respect privacy and licensing—never share sensitive data, and attribute external content properly.

Markdown

Most questions and replies can be handled without any fancy formatting, but for when it is necessary to add styling to text (e.g. bold, italics, or code blocks), you can use Markdown. Discourse uses markdown-it for its markdown implementation.

Callouts

The Speciforum uses the discourse-quote-callouts theme component adding a quick way to make certain pieces of content, notes, warnings, or other messages stand out. This is used extensively in our documentation.

Usage

To create a callout, add [!type] to the first line of a quote, where type is the type identifier. The type identifier determines how the callout looks and feels. To see all available types, refer to Supported types.

> [!tip]
> **Tip**: Use `code snippets` to enhance readability. They provide clarity and precision.

[!tip]
Tip: Use code snippets to enhance readability. They provide clarity and precision.

Custom title

By default, the title of the callout is its type identifier in title case. You can change it by adding text after the type identifier:

> [!question] Custom Label 🤗
> Callouts labels can be customized.

> [!abstract] [date=2032-12-22 timezone="Europe/Paris"]
> They can also contain special inline formating like dynamic dates.

[!question] Custom Label :hugs:
Callouts labels can be customized.

[!abstract] 2032-12-21T23:00:00Z
They can also contain special inline formatting like dynamic dates.

You can also create title-only callouts:

> [!success] Solved.

[!success] Solved.

Foldable callouts

You can make a callout foldable by adding a plus + or a minus - directly after the type identifier.

  • + expands the callout by default
  • - collapses it instead
> [!todo]- My Todo List
>
> - [x] Write documentation
> - [ ] Add tests
> - [ ] Review code

> [!todo] My Expanded Todo List
>
> - [x] Create repository
> - [ ] Setup CI/CD
> - [ ] Deploy to production

[!todo]- My Todo List

  • Write documentation
  • Add tests
  • Review code

[!todo] My Expanded Todo List

  • Create repository
  • Setup CI/CD
  • Deploy to production

Supported default types

You can use several callout types and aliases.
Each type comes with a different background color and icon.

Type Description Aliases
note For general notes and information -
abstract For summaries or abstract sections summary, tldr
info For informational content -
todo For task lists or todo items -
tip For tips and important information hint, important
success For success messages check, done
question For questions and FAQs help, faq
warning For warnings caution, attention
failure For failure notices fail, missing
danger For danger or error messages error
bug For bug reports or known issues -
example For examples -
quote For quotes cite

Buttons

To match the appearance of buttons in the application, you can add buttons that resemble those in Specify:

Simple Button

[wrap="simpleBtn"]Simple Button[/wrap]

Simple Button‎

Color Buttons

[wrap="blueBtn"]Blue Button[/wrap]‎ 
[wrap="orangeBtn"]Orange Button[/wrap]‎ 
[wrap="redBtn"]Red Button[/wrap]
[wrap="greenBtn"]Green Button[/wrap]

Blue Button‎

Orange Button‎

Red Button‎

Green Button‎

This is possible thanks to the discourse-buttons theme component that is installed in this instance. It is tracked via the linked GitHub repository.

Keyboard Keys

You can indicate that a particular key is to be pressed by wrapping the key in <kbd></kbd>.

For example:

<kbd>Ctrl</kbd> + <kbd>C</kbd> copies on Windows
<kbd>⌘</kbd> + <kbd>C</kbd> copies on a Mac

Ctrl + C copies on Windows
⌘ + C copies on a Mac

Icons

Many of the icons included in Specify 7 (mostly sourced from Heroicons v1 with several hand-drawn additions) are available on the forum as ‘emoji’. You can find and select these using the emoji picker:

Emoji
Emoji882×768 62.3 KB

Examples

:attachments_::data_entry_::gear_:
:interactions_::linkout_::search_:
:batchedit_: :queries_: :usercircle_: 
:specify: :specify6: :specify7:

:attachments_::data_entry_::gear_:
:interactions_::linkout_::search_:
:batchedit_: :queries_: :usercircle_:
:specify: :specify6: :specify7:

[!info]
Staff of the site can add additional icons using this link.

Icons ending with an underscore (_) will be inverted automatically in dark mode thanks to this theme component. If you add more icons in the future, make sure they end with an underscore.

These emojis can be updated and replaced at any time, ensuring all documentation is up-to-date with the latest iconography used in the application.