This document is written in dokuwiki.

The markup syntax is described here: https://www.dokuwiki.org/wiki:syntax

Embedded images.

• title after vertical bar
• Use white space to specify alignment: left, right, center.
• size as cgi parameter (after question mark)
• non-supported format as cgi parameter

{{ straight_line.png|Straight Line}}
{{straight_line.png|Straight Line }}
{{ straight_line.png|Straight Line }}
{{straight_line.png?300}}
{{straight_line.png?300x100}}
{{straight_line.svg?300&.png}}

We embed local video files uploaded to the media folder.

• Append ?540 to the filename to set the width.
• Beneath the embedded video, add an external link to the original source.

{{:elon_musk_mechanics.mp4?540 | Elon Musk on Mechanics}}
Video source: Joe Rogan podcast #1609, 12 Feb 2021 
[[https://spotify.com?204230984 | on Spotify]]

Note:

• Use OBS to capture the video (mkv)
• Use Blender to crop (mp4)
• Use https://www.videosmaller.com/ to optimize the filesize (mp4)

Also note:

• We tried to use Handbrake to optimize, but they output the (m4v) format and dokuwiki will not accept that.
• We also tried to embed YouTube videos. They do a great job of optimizing the download, but they insert distracting and irrelevant recommendations and other junk.

For math equations, we use the MathJax extension.

$$ \frac{\Delta f(x)}{\Delta x} = \frac{f(x+h)-f(x)}{(x+h)-(x)} = \frac{f(x+h)-f(x)}{h}$$

For upright text, use \text{hello} instead of \textup{hello}.

Align multiple equations like this:

\begin{align}
x   &= 3       & 10    &abc def\\
xyz &= a_2 b_3 & 1000  &xy\\
12  &= 8y^4           && explain\\
y   &= a_1 b_1        && this\\
\end{align}

\begin{align} x &= 3 & 10 &abc def\\ xyz &= a_2 b_3 & 1000 &xy\\ 12 &= 8y^4 && explain\\ y &= a_1 b_1 && this\\ \end{align}

The ampersands split the section into columns.
The columns alternate between right and left alignment.
Two adjacent ampersands skips a column.

\begin{align} x=1 &\iff y = 72 && \text{\iff} \\ x=2 &\therefore y = 43.2 && \text{\therefore} \\ x=3 &\rightarrow y = 25.92 && \text{\rightarrow} \\ x=4 &\Rightarrow y = 15.552 && \text{\Rightarrow} \\ x &= 30^\circ && \text{^\circ} \\ \end{align}

Edit math equations online here:
https://www.codecogs.com/latex/eqneditor.php

Reference list of math symbols:
https://oeis.org/wiki/List_of_LaTeX_mathematical_symbols#Set_and.2For_logic_notation

\chemfig not supported

For chemical formulas and equations we use the mhchem extension to the MathJax extension.

• Embed chemical notation in the \ce{} tag.
• Use the \require{mhchem} tag once on each page that uses \ce{}.

$$\require{mhchem}$$
$$\ce{H2O}$$
$$\ce{HCl (aq) + NaOH (aq) -> H2O (l) + NaCl (aq)}$$

$$\require{mhchem}$$ $$\ce{H2O}$$ $$\ce{HCl (aq) + NaOH (aq) -> H2O (l) + NaCl (aq)}$$

Edit chemical equations online here: http://visualmatheditor.equatheque.net/VisualMathEditor.html

mhchem reference, pdf

Made possible by plugin yalist, as used in ReStructered Text and Sphinx.

Definition List (deflist)

A list of terms and their definitions. Implemented with html dl, dt, and dd tags.

yalist

A plugin for dokuwiki that implements a definition list syntax

ReStructured Text (ReST)

A document format similar to Markdown, used in Python and Blender documentation.

Sphinx

A python software package that implements ReST.

? Definition List (deflist)
: A list of terms and their definitions.  Implemented with html dl, dt, and dd tags.
? yalist
: A plugin for dokuwiki that implements a definition list syntax
? ReStructured Text (ReST)
: A document format similar to Markdown, used in Python and Blender documentation.
? Sphinx
: A python software package that implements ReST.

Note. After installing the yalist plugin for dokuwiki, we modified the style.css file in the lib/plugin/yal/ directory.

We have these namespaces: Draft, UserGuide, Projects, Videos.

The first page in each namespace has the same name as the namespace and serves as the index page for that namespace. Example drafts:drafts.

In Admin-ACL, set permissions to none for @user and @ALL for namespace “draft”.

The word “Un1on” cannot be used in a dokuwiki page.

https://www.dokuwiki.org/faq:mod_security

• download in markdown format
• convert markdown to dokuwiki - https://www.markdowntoolbox.com/tools/convert-to-dokuwiki/
• fixup in vim
  • remove extra line endings in lists (see vim regexp below)
  • no more that one $ per line, or it triggers an equation
  • look for html entities like &
• paste into wiki

%s/\\\\\n\n\( \+\)\*/\r\1\*/
%s/\\\\\n\n\( \+\)\-/\r\1\-/
2,$s/===\(.*\)===/==\1==/

Locations:

• The user content resides in the curriculum project, which is in git.
• The wiki software resides in the samwiki project, which is NOT in git.

Therefore, samwiki can be upgraded or reinstalled anytime without affecting the user content.

Here is the procedure to upgrade samwiki/dokuwiki to the latest release,
largely copied from https://www.dokuwiki.org/install:upgrade.

# First, just to be safe, git commit all changes in the curriculum project.

# move to the samwiki folder
cd <production>/samwiki

# backup the current installation (just to be safe)
tar zcpfv dokuwiki-backup.tar.gz dokuwiki

# download and unzip the new release  
wget http://download.dokuwiki.org/src/dokuwiki/dokuwiki-2025-05-14b.tgz
tar zxvf dokuwiki-2025-05-14b.tgz

# cp the new release on top of the current installation
# this overwrites the executables, but does not affect the user data
cp dokuwiki-2025-05-14b/* dokuwiki/

In the samwiki folder:

• the dokuwiki subfolder contains the production installation
• the other files in samwiki are working files and can be deleted

Some notes about the cp command.

• After the cp command you may see messages like: “cp: omitting directory ‘dokuwiki-2025-05-14b/bin’”. This is normal. It means directory itself was not copied. The files within each directory were copied successfully.
• Many of the source directories are empty. Like data/pages for instance. That's how the cp effects an upgrade without overwriting the user data.
• The source data/pages/folder contains two subfolders: playground and wiki. These are not copied because cp does not create directories that are not pre-existing in the destination.

When to upgrade?
When dokuwiki has issued a new release, you will see a message like this at the top of every page in the wiki.

Hotfix release available: 2025-05-14b "Librarian". upgrade now! [56.2] (what's this?)

A complete list of the dokuwiki releases can be found here: https://download.dokuwiki.org/archive

Notice that a new release comes out every year, and lately each release has two hotfix releases: a, and b.

• 2025 11 15 upgraded to the 2025-05-14b “Librarian” hotfix-b release

# The dokuwiki executable is installed in samwiki.
# The pages, media, and conf files are stored in curriculum.
# Therefore,
#    1. the wiki data is version-controlled by the github curriculum project, and
#    2. the dokuwiki executable can be reinstalled, without risking loss of data.

# how to install into a2hosting

# 1. unzip dokuwiki into ~/webprod/samwiki
cd ~/webprod/samwiki
wget https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz
tar -xzvf dokuwiki-stable.tgz
mv dokuwiki-2022-07-31a/ dokuwiki

# 2. if necessary, upgrade PHP version at a2hosting CPanel "select PHP version"

# 3. run the dokuwiki install
http://curriculum.voyc.com/install.php
# Wiki Name: Curriculum
# Superuser: jhagstrand
# Real name: John Hagstrand
# E-Mail: john@hagstrand.com
# Password: know9
# once again: know9
# Initial ACL policy: Public Wiki
# Allow users to register themselves: no
# License: Public Domain

# 4. Point wiki pages, media, and conf files back to curriculum.
cd ~/webprod/samwiki/dokuwiki
ln -s ~/webprod/curriculum/curriculum/doc/dokuwiki/conf/userall.css conf/userall.css
ln -s ~/webprod/curriculum/curriculum/doc/dokuwiki/conf/entities.local.conf conf/entities.local.conf
mv data/pages data/pages-orginal
ln -s ~/webprod/curriculum/curriculum/doc/dokuwiki/data-pages data/pages
mv data/media data/media-orginal
ln -s ~/webprod/curriculum/curriculum/doc/dokuwiki/data-media data/media

# 5. Point curriculum to samwiki
cd ~/webprod/curriculum/curriculum
ln -s ~/webprod/samwiki/dokuwiki html

# 6. delete the install.php file
cd ~/webprod/samwiki/dokuwiki/
rm install.php

# 7. Install the mathjax plugin for equations.
cd ~/webprod/samwiki/dokuwiki/lib/plugins/
wget https://github.com/liffiton/dokuwiki-plugin-mathjax/archive/master.zip
# unzip and rename folders: lib/plugins/mathjax
unzip master.zip
mv dokuwiki-plugin-mathjax-master mathjax

#8. Install the yalist extension for definition lists.
# see https://www.dokuwiki.org/plugin:yalist
# Admin -> Extension Manager
# Search Extension: yalist
# yalist Plugin by Mark Prins  ::  Install
# after install, modify the style.css file as follows
vi ~/webprod/samwiki/dokuwiki/lib/plugins/style.css
# div.dokuwiki .dt {
#     color: black;      /* __text_alt__; */
#     max-width: 50%;    /* 30%           */
#     float: none;       /* left;         */
# div.dokuwiki dd {
#     margin-bottom: 0.5em;  /* (new) */

# 9. Test extensions on "curriculum - appendix - dokuwiki" page.

#10. Upload logo.png in Media Manager.

#11. In Administrator, ACL, set permissions on draft namespace.
#     @ALL none
#     @user none

fold these to files into this page

• markdown_to_dokuwiki_macro.txt
• sample_dokuwiki_syntax.txt

sample dokuwiki page