neale/moth
neale
/
moth
mirror of https://github.com/dirtbags/moth.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Development doc more approachable?

This commit is contained in:
Neale Pickett 2023-12-11 11:36:18 -07:00
parent 60fdb0ddd8
commit bbb5a5484a
2 changed files with 172 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/content-layout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

248
docs/development.md
View File

@ -1,105 +1,201 @@
Developing Content Developing Content: Structure
============================ ================
The development server shows debugging for each puzzle, ![Content Layout](content-layout.png)
and will compile puzzles on the fly.
Use it along with a text editor and shell to create new puzzles and categories. MOTH content is structured ot two levels: categories, and puzzles.
Category
-------
Set up some example puzzles A category consists of one or more puzzles.
--------- Each puzzle is named by its point value,
and each point value must be unique.
For instance,
you cannot have two 5-point puzzles in a category.
If you don't have puzzles of your own to start with, Scoring is usually calculated by summing the
you can copy the example puzzles that come with the source: *percentage of available points per category*.
This allows content developers to focus only on point values within a single category:
how points are assigned in other categories doesn't matter.
cp -r /path/to/src/moth/example-puzzles /srv/moth/puzzles Puzzle
Run the server in development mode
---------------
These recipes run the server in the foreground,
so you can watch the access log and any error messages.
### Podman
podman run --rm -it -p 8080:8080 -v /srv/moth/puzzles:/puzzles:ro ghcr.io/dirtbags/moth-devel
### Docker
docker run --rm -it -p 8080:8080 -v /srv/moth/puzzles:/puzzles:ro ghcr.io/dirtbags/moth-devel
### Native
I assume you've built and installed the `moth` command from the source tree.
If you don't know how to build Go packages,
please consider using Podman or Docker.
Building Go software is not a skill related to running MOTH or puzzle events,
unless you plan on hacking on the source code.
mkdir -p /srv/moth/state
cp -r /path/to/src/moth/theme /srv/moth/theme
cd /srv/moth
moth -puzzles puzzles
Log In
----- -----
Point a browser to http://localhost:8080/ (or whatever host is running the server). A puzzle consists of a few static fields,
You will be logged in automatically. a main puzzle body,
and optionally attached files.
At a minimum,
a puzzle must contain `puzzle.md`:
a
[CommonMark Markdown](https://spec.commonmark.org/dingus/)
file with metadata.
Example:
```markdown
---
authors:
- Neale Pickett
answers:
- one of its legs are both the same
- One of its legs are both the same
- one of its legs are both the same.
- One of its legs are both the same.
---
This puzzle consists of a joke.
What is the difference between a duck?
```
### Puzzle Metadata
Puzzle metadata is the section of `puzzle.md` between `---`.
This section consists of [YAML](https://yaml.org/),
describing various metadata aspects of the puzzle.
At a minimum,
each puzzle should contain:
* authors: who created the puzzle
* answers: a list of answers that are considered "correct"
Other metadata a puzzle can contain:
* debug: information used only in development mode
* summary: text summarizing what this puzzle is about
* notes: any additional notes you think it's important to record
* hints: a list of hints that could aid an instructor
* objective: what the goal of this puzzle is
* ksas: a list of NICE KSAs covered by this puzzle
* success: criteria for success
* acceptable: criterion for acceptably succeeding at the task
* mastery: criterion for mastery of the task
* attachments: a list of files to attach to this puzzle (see below)
### Body
The body of a puzzle is interpreted as
[CommonMark Markdown](https://spec.commonmark.org/dingus/)
and rendered as HTML.
You can inline attached images with the `![alt text](filename.jpg)`
Markdown construct, but they must be listed as attachments!
### Attachments
Any filenames listed under `attachments` in the metadata will be included
with the puzzle.
Browse the example puzzles Developing Content: Source vs Mothballs
------------ =============================
As a developer,
you will begin by running MOTH in development mode.
In development mode,
MOTH will provide answers for each puzzle alongside the puzzle.
In order to run in production mode,
each category must be "transpiled" into a "mothball".
This is done to reduce the amount of dynamic code running on a production server,
as a way of decreasing the attack surface of the server.
To obtain a mothball,
simply click the "download" button on the puzzles list of a development server.
Mothballs have the file extension `.mb`.
The example puzzles are written to demonstrate various features of MOTH, Setting Up Your Workstation
and serve as documentation of the puzzle format. =====================
You will need two things to develop content:
a MOTH server,
and a text editor.
MOTH Server
-----------
### Windows
Windows users can unzip the zip file provided by the MOTH development team,
and run `moth-devel.bat`.
You can close this window whenever you're done developing.
Once started,
open
http://localhost:8080/
to connect to your development server.
### Linux
Linux users with Docker can run the following to get started
```sh
mkdir -p puzzles
docker run --rm -it -p 8080:8080 -v $(pwd)/puzzles:/puzzles:ro ghcr.io/dirtbags/moth-devel
```
Hit Control-C to terminate MOTH.
Make your own puzzle category Text Editor
------------------------- ---------
cp -r /srv/moth/puzzles/example /srv/moth/puzzles/my-category We like Visual Studio Code,
but any text editor will work:
you only need to edit the `puzzle.md` (Markdown) files.
Your First Category
================
Edit the one point puzzle Open the `puzzles` directory/folder created where you launched the server.
-------- Create a new directory/folder named `test-category`.
Within that directory/folder,
create a directory/folder named `1`.
And within `1`,
create a new file named `puzzle.md`.
Paste the following text into that file:
nano /srv/moth/puzzles/my-category/1/puzzle.md ```markdown
---
authors:
- YOUR NAME HERE
answers:
- Elephant
- elephant
---
I don't use nano, personally, # Animal Time
but if you're advanced enough to have an opinion about nano,
you're advanced enough to know how to use a different editor.
Do you like animals? I do!
Can you guess my favorite animal?
```
Read our advice Now,
--------------- open http://localhost:8080/ in a web browser.
You should see a "test-category" category,
with a single 1-point puzzle.
Click that puzzle,
and you should see your animal puzzle presented.
The two answers we're accepting can be improved,
because some people might use the plural.
Edit `puzzle.md` to add two new answers:
`Elephants` and `elephants`.
Reload the web page,
and check the debug section to verify that all four answers are now accepted.
Next Steps
==========
The [Writing Puzzles](writing-puzzles.md) document The [Writing Puzzles](writing-puzzles.md) document
has some tips on how we approach puzzle writing. has some tips on how we approach puzzle writing.
There may be something in here that will help you out! There may be something in here that will help you out!
Stop the server
-------
You can hit Control-C in the terminal where you started the server,
and it will exit.
Mothballs
=======
In the list of puzzle categories and puzzles,
there will be a button to download a mothball.
Once your category is set up the way you like it, Once your category is set up the way you like it,
download a mothball for it, download a mothball for it,
and you're ready to [get started](getting-started.md) and you're ready for [getting started](getting-started.md)
with the production server. with the production server.