pupate

category-format.md

  1---
  2title: Category Format
  3---
  4
  5Categories may have front matter and a page,
  6stored in the file `category.md` in the category's directory 
  7(alongside puzzle directories).
  8
  9Category files are formatted similarly to [puzzles](puzzle-format.md).
 10
 11
 12Example
 13===========
 14
 15This category lists all front matter fields.
 16You are not required to list all these,
 17or even 
 18
 19```markdown
 20---
 21# title of this category, displayed to participants instead of the directory name
 22# if enabled by the MOTH administrator
 23title: Example Category
 24
 25# version of this category. Not used by Cyber Fire.
 26version: 1.0
 27
 28# blueprint specifies the SCTR blueprint to use. Not used by Cyber Fire.
 29blueprint: 2837
 30
 31# prerequisites for this category. This may be displayed to participants, to help them decide
 32# if they are ready for this category.
 33prerequisites:
 34  - Understand the concept of color (being able to discern colors is not necessary)
 35  - Know the names of the primary and secondary colors
 36  - A Commodore-64 or Commodore PET
 37  - Emacs 29.3
 38
 39# unlocked will cause all puzzles to be available at start: nothing needs to be "unlocked".
 40# Not used by SCTR.
 41unlocked: true
 42
 43# params are free YAML, and can be used to add anything you like to a category.
 44# Variants can access these values through the value {{.Params}}
 45params:
 46  a: params can be any YAML type, although using a dictionary would be wise,
 47    since it allows for future growth.
 48  b: this is mostly here in case we need to add new features without needing a new pupate version.
 49---
 50
 51What is the best color?
 52```
 53
 54Markdown flavor
 55=============
 56
 57Use CommonMark.
 58
 59The markdown parser used internally is Goldmark.
 60Some servers, like SCTR, do their own Markdown formatting,
 61but seem to adhere to CommonMark.
 62
 63If your puzzle output uses the build-in renderer,
 64you can take advantage of the following extensions:
 65
 66
 67Tables
 68------
 69
 70https://github.github.com/gfm/#tables-extension-
 71
 72```
 73| x   | y   | x + y |
 74| --- | --- | ----- |
 75| 1   | 2   | 3     |
 76| 10  | 2   | 12    |
 77```
 78
 79
 80Definition lists
 81-----------
 82
 83https://michelf.ca/projects/php-markdown/extra/#def-list
 84
 85```
 86Green
 87: The best color. 
 88  The color of pine tree needles,
 89  until bark beetles invade.
 90
 91Orange
 92: A color that doesn't have any easy rhymes.
 93```
 94
 95
 96Footnotes
 97--------
 98
 99https://michelf.ca/projects/php-markdown/extra/#footnotes
100
101```
102I like pie.[^1] 
103Other notable people who like pie: 
104clowns, Weebl and Bob, Cartman.
105
106[^1]:
107    Fruit pies are my favorite. 
108    Gourd pies, like pumpkin, are not my favorite.
109```
110
111
112Attachments
113==========
114
115If you want any other files in your puzzle directory on the server,
116you must list them as `attachments`.
117This includes inline images.
118
119Listing an attachment will usually cause that file to be listed as an attachment
120in the user interface:
121even inline images.
122There is no way to "hide" an attachment.
123
124
125Template functions
126==========
127
128Puzzles may use Go `text/template` directives,
129with the following additions:
130
131    sum
132        Returns the sum of its arguments.
133
134    json
135        Returns the JSON encoded equivalent of its argument.
136
137    currentuser
138        Returns the current user as a structure,
139        with values .Uid, .Gid, .Username, .Name, and .HomeDir.
140        The following works like you expect:
141            {{currentuser.Name}
142        On my Windows computer, disconnected from the domain controller,
143        This takes 5-30 seconds the first time it's run!
144
145    skip
146        Do not write this file in the output directory.
147        This is used by MOTHv5 templates to conditionally
148        write feature flag files.
149
150    .RelPath
151        Returns the relative path of its argument.
152        This is most useful when linking attachments.
153
154    .SrcPath
155        Returns the OS path to its argument in the puzzle source directory.
156
157    .PrefixAttachments
158        Prepend the first argument to every instance of an attachment
159        in the second argument. This is used in variants that must prefix all
160        links with some string.