# Speciforum Contribution Style Guide **URL:** \ **Category:** Welcome Specify Members\ **Created:** [June 8, 2025, 3:13pm UTC](https://speciforum.org/t/speciforum-contribution-style-guide/2616 "2025-06-08T15:13:32Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Grant](https://yyz1.discourse-cdn.com/flex029/user_avatar/speciforum.org/grant/32/4255_2.png) [@Grant](https://speciforum.org/u/Grant)\ **Post date:** [June 8, 2025, 3:13pm UTC](https://speciforum.org/t/speciforum-contribution-style-guide/2616/1 "2025-06-08T15:13:32Z")
# Style Guide for Speciforum Contributors This style guide is exclusively for contributors to the **[Specify Community Forum](https://speciforum.org)** (the site you are on now)! This forum is referred to only as the **Speciforum** , not ‘Discourse’ or any other name. ## 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](https://github.com/markdown-it/markdown-it) for its markdown implementation. > **[Formatting posts using markdown, BBCode, and HTML](https://meta.discourse.org/t/formatting-posts-using-markdown-bbcode-and-html/239348)** > > 🔖 This reference guide details all the formatting options available in Discourse posts, including markdown, BBCode, and HTML. It specifies what is supported and provides resources where you can see examples. 🙋 Required user level: All users ... ## Code Blocks Snippets of code are occasionally exchanged in conversations on the forum. If you are sharing a snippet of XML as a reference, please include it as a code block rather than as an image. You can do this by following the [guides from Discourse on code blocks](https://meta.discourse.org/t/selecting-the-programming-language-used-in-code-blocks/19247). ```` ```xml ``` ```` If you are referencing a particular data model or database field, please make sure to wrap it in single backticks (e.g. ``). See below: _The fields `cataloger`, `text1` and `collectionObjectType` are on the `CollectionObject` table._ If you are including code from the GitHub repository, please [copy the lines](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet) from the project files directly rather than pasting plain text here. ## Callouts The Speciforum uses the [`discourse-quote-callouts`](https://github.com/Arkshine/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. ```markdown > [!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: ```markdown > [!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 🤗 > 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: ```markdown > [!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 ```markdown > [!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 ```auto [wrap="simpleBtn"]Simple Button[/wrap] ``` Simple Button‎ ### Color Buttons ```auto [wrap="blueBtn"]Info Button[/wrap]‎ [wrap="specifyBtn"]Specify Green Button[/wrap]‎ [wrap="redBtn"]Danger Button[/wrap] [wrap="greenBtn"]Success Button[/wrap] ``` Info Button‎ Specify Green Button‎ Danger Button‎ Success Button‎ This is possible thanks to the [`discourse-buttons`](https://github.com/specify/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 ``. For example: ```md Ctrl + C copies on Windows ⌘ + C 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](https://heroicons.dev/?iconset=v1-20-solid) with several hand-drawn additions) are available on the forum as ‘emoji’. You can find and select these using the [emoji picker](https://blog.discourse.org/2015/12/emoji-and-discourse/): ![Emoji](https://canada1.discourse-cdn.com/flex029/uploads/specifysoftware/original/2X/a/a00f315cfb3f42c096533d1c42c49c14d9ba6bb0.png) ### Examples ```shell :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](https://speciforum.org/admin/customize/emojis). > > Icons ending with an underscore (`_`) will be inverted automatically in dark mode thanks to this [theme component](https://github.com/specify/discourse-buttons). 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.