Style Guide for Speciforum Contributors
This style guide is exclusively for contributors to the Specify Community Forum (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 for its markdown implementation.
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.
```xml
<row>
<cell type="label" labelfor="FieldNumber"/>
<cell type="field" id="FieldNumber" name="fieldNumber" uitype="text" colspan="3"/>
<cell type="label" labelfor="Collecting Field Number"/>
<cell type="field" id="Collecting Field Number" name="collectingEvent.stationFieldNumber" uitype="text" colspan="3"/>
</row>
```
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 from the project files directly rather than pasting plain text here.
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: Usecode snippetsto 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
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:
Examples
: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.