Differences

This shows you the differences between two versions of the page.

--- software:dokuwiki [2025/12/22 02:03] – diamond
+++ software:dokuwiki [2026/01/07 08:33] (current) – add note on wrap plugin diamond
@@ Line 2: / Line 2: @@
 dma.space operates a Dokuwiki instance at [wiki.dma.space](https://wiki.dma.space).
+## Markdown by Default
+Our Dokuwiki instance runs the [Commonmark plugin](https://www.dokuwiki.org/plugin:commonmark), which is configured to treat every page as Markdown files **by default**. To create a page, you just type in normal Markdown, and it just works.
+**This plugin has a few quirks that you should keep in mind:**
+- Some inline Dokuwiki syntax are still supported. For example, the "Add image" button in the editor still works, even though it inserts Dokuwiki markup.
+- Some Commonmark syntax are parsed incorrectly by the plugin. For example, list items with multiple text paragraphs are not supported.
+- You may add custom Dokuwiki markup by opening a code block with a `dokuwiki` language. The [main page](/) utilizes this; just look at its source code.
+- The main editor is [TinyMDE](#tinymde), not Dokuwiki's default editor.
+### Admonitions
+The custom CSS adds very basic Markdown Admonitions into Dokuwiki. Here's an example of how one could look like:
+> **Note:** Fire Warning
+>
+> This device may catch fire. Use with caution.
+Here's the code for it:
+```
+> **Note:** Fire Warning
+>
+> This device may catch fire. Use with caution.
+```
+For this to work, the first text part of the blockquote must be a bold string (`**bold**`). The CSS will automatically style it like the above.
+### TinyMDE
+We use [TinyMDE](https://github.com/jefago/tiny-markdown-editor) as the default page editor for Dokuwiki. This is done via custom userscripts that automatically replace the editor on load.
+If this is breaking for some reason, you may revert to the previous editor by adding `tinymde=no` to the query URL, e.g. `https://wiki.dma.space/page?do=edit&tinymde=no`.
+### Images
+TinyMDE's toolbar contains a custom image button that spawns the normal Media Manager dialog, but you won't be able to choose alignment, size and other parameters using this dialog. Instead, the dialog just lets you upload files and insert image links (in Markdown) to the editor.
+For reference:
+- To set the width of the image to 100, add `?100` to the end of the image URL.
+- To set the height of the image to 100, add `?0x100` to the end of the image URL.
+- To center the image, wrap it in a `<div centeralign>` block like you would in HTML. Note that this isn't actually HTML but rather custom Dokuwiki markup intermingling with Markdown.
+### Format using Prettier
+The sparkly button on the editor toolbar will format the entire page's source using Prettier as a Markdown file. **DO NOT run this if the page is written entirely in Dokuwiki markup.**
+It is recommended that you run this tool whenever you paste any Markdown snippet from outside.
+### Aligning Content
+We run the [Wrap plugin](https://www.dokuwiki.org/plugin:wrap), which lets you do layouting tricks, such as aligning images in the center:
+```
+<div centeralign>
+  ![](path/to/image.jpg)
+</div>
+```
+Refer to their documentation for more information.
+## Namespacing
+Dokuwiki uses this concept of a "namespace". You may understand it as folders that files go in.
+For example, `:hardware:nixos-boxes` means that the page **or** namespace `nixos-boxes` sits inside the `hardware` namespace. As paths, it would be written as `/hardware/nixos-boxes` (this format is used in URLs).
+Keep in mind that **a namespace starts out as a page**, and that pages can become namespaces later on. For example, the page at `:hardware:nixos-boxes` can become a namespace if we just create a page underneath it, e.g. at `:hardware:nixos-boxes:example`. As folders, this would be akin to having a `README.md` file and a bunch of children folders next to it.
+### Creating a Page
+Dokuwiki doesn't have a straightforward way of creating a new page, but we made it easier with a plugin. You can see this plugin at the bottom of [the main page](/) as a simple input box:
+{{:software:screenshot_from_2025-12-21_18-06-24.png?400}}
+To create a new page using this input box:
+. Select an existing category on the left dropdown input (shown above).
+. Type in the **slug** of the page (i.e. hyphenated words such as "this-page", **NOT** the actual name like "This page").
+. Click **Add page**.
+Once you're on the editing page, give the page a title in Markdown format on the first line, e.g. `# This page`, then hit **Save**. This will automatically create the page.
+### Creating a Namespace
+There is no straightforward button for creating a namespace, but you can do so using the same "Add page" input box above.
+For example, if `:hardware:nixos-boxes` is currently a page, and I want to make a page underneath that page, I would select `hardware` as the namespace, and type in `:nixos-boxes:new-page` as the slug.
+I could also keep the namespace selector as `Root` and create a page with the slug `:hardware:nixos-boxes:new-page`. This does the same thing.
+To start with, namespace pages should start out with its title and a small list of its inner pages, if possible. Here's a copy-paste template:
+````
+# Namespace Name
+**Pages:**
+```dokuwiki
+<catlist :path:to:namespace -noHead>
+```
+````
 ## Theming
 Our instance uses a patched version of the [Mikio](https://www.dokuwiki.org/template:mikio) template. We patched it to change its colors to better fit dma.space's branding, and to make it work better on mobile and on non-JavaScript environments.
+These patchsets are maintained by a set of NixOS configurations. See [NixOS Boxes](/infrastructure/nixos-boxes) for more information.