pupate

puzzle-format.md

  1---
  2title: Puzzle Format
  3---
  4
  5Puzzles are stored in `puzzle.md`,
  6in a directory below the category directory.
  7
  8Puzzles directories are usually sorted with a "Natural Sort",
  9which will sort numbers the way humans expect (eg 1, 2, 11, 21).
 10
 11Puzzles are formatted in
 122024-era Markdown,
 13with YAML front matter.
 14
 15
 16Example
 17===========
 18
 19This puzzle uses every front matter field available.
 20Pupate/Cocoon considers every field optional,
 21although your variant (eg Cyber Fire or SCTR)
 22may throw an error if important fields are missing.
 23You should usually specify at least an answer, though :)
 24
 25```markdown
 26---
 27# titles will be displayed instead of puzzle directory names,
 28# if your MOTH administrator enables it.
 29title: Example Puzzle
 30
 31# authors lists the names of the people who worked on this puzzle.
 32authors:
 33  - alice
 34  - bob
 35
 36# answerpattern specifies a regular expression used by browser to turn the input box red
 37# if the text doesn't match. It is not used by the MOTH server to validate answers,
 38# it's browser-only.
 39answerpattern: "[A-Za-z]+"
 40
 41# question will be displayed before the answer input. If unspecified,
 42# generic text will be displayed (something like "Answer:")
 43question: What is your favorite color?
 44
 45# answers lists all acceptable answers. These are case-sensitive exact string matches.
 46answers:
 47  - green
 48  - Green
 49  - GREEN
 50
 51# attachments lists any files associated with this puzzle. If you specify an attachment
 52# that doesn't exist, pupate/cocoon will throw an error.
 53attachments:
 54  - green-square.png
 55
 56# scripts are included with the page, to provide enhanced functionality such as 
 57# fancy input mechanisms or calculators.
 58scripts:
 59  - green-text.mjs
 60
 61# objectives for this puzzle. This may be displayed to participants, to help them understand
 62# why they're doing this.
 63objectives: 
 64  - Learn what the best color is.
 65
 66# prerequisites for this puzzle. This may be displayed to participants, to help them decide
 67# if they are ready for this puzzle.
 68prerequisites:
 69  - Understand the concept of color (being able to discern colors is not necessary)
 70  - Know the names of the primary and secondary colors
 71  - A Commodore-64 or Commodore PET
 72  - Emacs 29.3
 73
 74# ksas lists NICE KSA(T) identifiers. These explain to participants and their management
 75# what abilities a participant can claim if they provide the correct answer.
 76ksas:
 77  - K942
 78  - K983
 79
 80# success lists criteria for being able to claim you understand this puzzle.
 81success:
 82  acceptable: begrudgingly accept that green is the only answer judged correct
 83  mastery: understand at a deep emotional level why green is the best color
 84
 85# debug fields are only shown in cocoon. They can be used to communicate hints,
 86# a puzzle summary, and notes, to staff during an event. The log section is sometimes
 87# used by scripts to help debug execution.
 88debug:
 89  summary: You have to say green.
 90  hints:
 91    - It is one of the primary colors.
 92    - Some say it's not easy being this color.
 93  notes:
 94    - although fully color-blind and completely blind students may not be able to achieve mastery,
 95      an acceptable level of success is still within reach.
 96  log:
 97    - Scripted puzzles might drop log output here for debugging.
 98    - Build time: 12ms
 99
100# params are free YAML, and can be used to add anything you like to a puzzle.
101# Variants can access these values through the value {{.Params}}
102params:
103  a: params can be any YAML type, although using a dictionary would be wise,
104    since it allows for future growth.
105  b: this is mostly here in case we need to add new features without needing a new pupate version.
106---
107
108What is the best color?
109```
110
111Markdown flavor
112=============
113
114Use CommonMark.
115
116The markdown parser used internally is Goldmark.
117Some servers, like SCTR, do their own Markdown formatting,
118but seem to adhere to CommonMark.
119
120If your puzzle output uses the build-in renderer,
121you can take advantage of the following extensions:
122
123
124Tables
125------
126
127https://github.github.com/gfm/#tables-extension-
128
129```
130| x   | y   | x + y |
131| --- | --- | ----- |
132| 1   | 2   | 3     |
133| 10  | 2   | 12    |
134```
135
136
137Definition lists
138-----------
139
140https://michelf.ca/projects/php-markdown/extra/#def-list
141
142```
143Green
144: The best color. 
145  The color of pine tree needles,
146  until bark beetles invade.
147
148Orange
149: A color that doesn't have any easy rhymes.
150```
151
152
153Footnotes
154--------
155
156https://michelf.ca/projects/php-markdown/extra/#footnotes
157
158```
159I like pie.[^1] 
160Other notable people who like pie: 
161clowns, Weebl and Bob, Cartman.
162
163[^1]:
164    Fruit pies are my favorite. 
165    Gourd pies, like pumpkin, are not my favorite.
166```
167
168
169Attachments
170==========
171
172If you want any other files in your puzzle directory on the server,
173you must list them as `attachments`.
174This includes inline images.
175
176Listing an attachment will usually cause that file to be listed as an attachment
177in the user interface:
178even inline images.
179There is no way to "hide" an attachment.
180
181
182Template functions
183==========
184
185Puzzles may use Go `text/template` directives,
186with the following additions:
187
188    sum
189        Returns the sum of its arguments.
190
191    json
192        Returns the JSON encoded equivalent of its argument.
193
194    currentuser
195        Returns the current user as a structure,
196        with values .Uid, .Gid, .Username, .Name, and .HomeDir.
197        The following works like you expect:
198            {{currentuser.Name}
199        On my Windows computer, disconnected from the domain controller,
200        This takes 5-30 seconds the first time it's run!
201
202    skip
203        Do not write this file in the output directory.
204        This is used by MOTHv5 templates to conditionally
205        write feature flag files.
206
207    .RelPath
208        Returns the relative path of its argument.
209        This is most useful when linking attachments.
210
211    .SrcPath
212        Returns the OS path to its argument in the puzzle source directory.
213
214    .PrefixAttachments
215        Prepend the first argument to every instance of an attachment
216        in the second argument. This is used in variants that must prefix all
217        links with some string.