Neale Pickett
·
2023-12-11
development.md
1Developing Content: Structure
2================
3
4
5
6MOTH content heirarchy consists of three layers:
7categories, puzzles, and attachments.
8
9Category
10-------
11
12A category consists of one or more puzzles.
13Each puzzle is named by its point value,
14and each point value must be unique.
15For instance,
16you cannot have two 5-point puzzles in a category.
17
18Scoring is usually calculated by summing the
19*percentage of available points per category*.
20This allows content developers to focus only on point values within a single category:
21how points are assigned in other categories doesn't matter.
22
23Puzzle
24-----
25
26A puzzle consists of a few static fields,
27a main puzzle body,
28and optionally attached files.
29
30At a minimum,
31a puzzle must contain `puzzle.md`:
32a
33[CommonMark Markdown](https://spec.commonmark.org/dingus/)
34file with metadata.
35
36Example:
37
38```markdown
39---
40authors:
41 - Neale Pickett
42answers:
43 - one of its legs are both the same
44 - One of its legs are both the same
45 - one of its legs are both the same.
46 - One of its legs are both the same.
47---
48
49This puzzle consists of a joke.
50
51What is the difference between a duck?
52```
53
54### Puzzle Metadata
55
56Puzzle metadata is the section of `puzzle.md` between `---`.
57This section consists of [YAML](https://yaml.org/),
58describing various metadata aspects of the puzzle.
59
60At a minimum,
61each puzzle should contain:
62
63* authors: who created the puzzle
64* answers: a list of answers that are considered "correct"
65
66Other metadata a puzzle can contain:
67
68* debug: information used only in development mode
69 * summary: text summarizing what this puzzle is about
70 * notes: any additional notes you think it's important to record
71 * hints: a list of hints that could aid an instructor
72* objective: what the goal of this puzzle is
73* ksas: a list of NICE KSAs covered by this puzzle
74* success: criteria for success
75 * acceptable: criterion for acceptably succeeding at the task
76 * mastery: criterion for mastery of the task
77* attachments: a list of files to attach to this puzzle (see below)
78
79### Body
80
81The body of a puzzle is interpreted as
82[CommonMark Markdown](https://spec.commonmark.org/dingus/)
83and rendered as HTML.
84
85Attachments
86-------
87
88Any filenames listed under `attachments` in the metadata will be included
89with the puzzle.
90
91Usually,
92these are listed at the bottom of each puzzle,
93one by one.
94But you can also refer to attachments from the puzzle body
95with either links or inline images.
96
97```markdown
98This is a [link](attachment-document.html).
99And this is an inline image: 
100```
101
102
103Developing Content: Source vs Mothballs
104=============================
105
106As a developer,
107you will begin by running MOTH in development mode.
108In development mode,
109MOTH will provide answers for each puzzle alongside the puzzle.
110
111In order to run in production mode,
112each category must be "transpiled" into a "mothball".
113This is done to reduce the amount of dynamic code running on a production server,
114as a way of decreasing the attack surface of the server.
115
116To obtain a mothball,
117simply click the "download" button on the puzzles list of a development server.
118Mothballs have the file extension `.mb`.
119
120
121Setting Up Your Workstation
122=====================
123
124You will need two things to develop content:
125a MOTH server,
126and a text editor.
127
128MOTH Server
129-----------
130
131### Windows
132
133Windows users can unzip the zip file provided by the MOTH development team,
134and run `moth-devel.bat`.
135You can close this window whenever you're done developing.
136
137Once started,
138open
139http://localhost:8080/
140to connect to your development server.
141
142### Linux
143
144Linux users with Docker can run the following to get started
145
146```sh
147mkdir -p puzzles
148docker run --rm -it -p 8080:8080 -v $(pwd)/puzzles:/puzzles:ro ghcr.io/dirtbags/moth-devel
149```
150
151Hit Control-C to terminate MOTH.
152
153
154Text Editor
155---------
156
157We like Visual Studio Code,
158but any text editor will work:
159you only need to edit the `puzzle.md` (Markdown) files.
160
161Your First Category
162================
163
164Open the `puzzles` directory/folder created where you launched the server.
165Create a new directory/folder named `test-category`.
166Within that directory/folder,
167create a directory/folder named `1`.
168And within `1`,
169create a new file named `puzzle.md`.
170Paste the following text into that file:
171
172```markdown
173---
174authors:
175 - YOUR NAME HERE
176answers:
177 - Elephant
178 - elephant
179---
180
181# Animal Time
182
183Do you like animals? I do!
184Can you guess my favorite animal?
185```
186
187Now,
188open http://localhost:8080/ in a web browser.
189You should see a "test-category" category,
190with a single 1-point puzzle.
191Click that puzzle,
192and you should see your animal puzzle presented.
193
194The two answers we're accepting can be improved,
195because some people might use the plural.
196Edit `puzzle.md` to add two new answers:
197`Elephants` and `elephants`.
198Reload the web page,
199and check the debug section to verify that all four answers are now accepted.
200
201Next Steps
202==========
203
204The [Writing Puzzles](writing-puzzles.md) document
205has some tips on how we approach puzzle writing.
206There may be something in here that will help you out!
207
208Once your category is set up the way you like it,
209download a mothball for it,
210and you're ready for [getting started](getting-started.md)
211with the production server.