harryob/od-dm-reference

OpenDream DreamMaker Reference

This project serves the DreamMaker reference, as implemented by OpenDream. We use Zola to build our website.

Contributing to the Reference

DreamMaker objects are kept under content/objects, with the _index.html pages under a directory providing that section's page. Procs and vars belonging to that object are kept under the respective proc and var sections.

Locally previewing the site

All you need is Zola¹. The instructions to install Zola are here. You can then run zola serve to preview the site as you edit the Markdown files. You will notice that the navigation bar is incomplete - that is to optimize serve times locally. You can override this behavior with ZOLA_ENV=prod zola serve - but compile times may take up to 30 seconds.

If you are altering site CSS, we currently use TailwindCSS (for now!), and you can edit class names to include Tailwind tags. Simply use npm install and npm run watch, which will run both zola serve (to update site contents) and tailwind -w (to update CSS).

Valid shortcodes

We can use shortcodes to render specific HTML within our Markdown files. They're invoked like this:

{{ some_shortcode(some_keyword_argument="some value!") }}

Currently, we have 4 callout shortcodes, which all take a description argument:

• never_implemented
• od_only
• parity
• unimplemented

To link to specific types, we can use the type shortcodes, such as:

{{ mob() }}

This also allows us to link to specific procs/vars on objects, using this syntax:

{{ client(proc="Export")} }

To read up on how to make shortcodes, the Zola documentation is here. All of our shortcodes live in templates/shortcode.

Autodocumentation

Most of the global procs, and objects procs and vars are automatically documented using the OpenDreamDocumentationTool, which runs periodically to update this reference from the DMStandard. These are all automatically updated:

• Global procs
• New objects
• Object vars
• Object procs

And these frontmatter fields are automatically populated:

• Procs

  • Name (title)
  • Arguments (args): name and type are derived from DMStandard, but the description field is set manually
  • Return type (return_type)
  • Override status (is_override)
  • Unimplemented status (od_unimplemented)

• Vars

  • Name (title)
  • Default value (default_value)
  • Type (type)
  • Override status (is_override)
  • Unimplemented status (od_unimplemented)

Autogen Comments

Fields filled in by the Autodocumentation Tool have specific comments, which mean:

• AUTOGEN FIELD - This field is generated by the tool, but can be overriden with AUTOGEN SKIP.
• AUTOGEN STATIC - This field is generated by the tool, and cannot be overriden. It should be changed in DMStandard.
• AUTOGEN SKIP - This is manually added by an author who has overridden the output of an AUTOGEN FIELD. This stops the tool from overwriting the contents.

Not Autodocced

"Procs" that are implemented as defines in DMStandard are not automatically populated. For example, ASSERT and REGEX_QUOTE. Furthermore, many procs are not present in DMStandard, such as istype() and prob() - these can be found here in the OpenDream source code.

[extra] Documentation

Zola allows us to put arbitrary TOML under the [extra] section, which we do for the various page types. This includes the fields that editors can set, not the ones pulled from DMStandard (above).

• Objects:
  • parent_type - This allows us to construct the parent types for any object - such as /mob going to /atom/movable, then /atom, then /datum.
• Procs:
  • return_type_desc - This allows us to add extra information about the return type - for example, what specific return types mean. It can also be used to document the return type if not pulled from DMStandard.
  • [[args.description]] - We can document individual arguments to procs with the description field.
  • [[args.od_unimplemented]] - If this argument is implemented or not in the OpenDream implementation of BYOND.
• Vars:
  • default_value_desc - This allows us to add extra information about the default value that this variable is set to.

Available markdown formatting

Zola uses CommonMark and the pulldown-cmark parser.

Syntax highlighting

We support DreamMaker syntax highlighting, with the following:

```dm
var/my_variable
```

This is based on our .sublime-syntax file. This can be updated as necessary to keep up with the language.

Footnotes

1. As long as you are not altering site CSS. ↩