diff --git a/docs/content-layout.png b/docs/content-layout.png new file mode 100644 index 0000000..b88e40c Binary files /dev/null and b/docs/content-layout.png differ diff --git a/docs/development.md b/docs/development.md index ccc789a..f737dec 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,105 +1,201 @@ -Developing Content -============================ +Developing Content: Structure +================ -The development server shows debugging for each puzzle, -and will compile puzzles on the fly. +![Content Layout](content-layout.png) -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, -you can copy the example puzzles that come with the source: +Scoring is usually calculated by summing the +*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 - - -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 +Puzzle ----- -Point a browser to http://localhost:8080/ (or whatever host is running the server). -You will be logged in automatically. +A puzzle consists of a few static fields, +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, -and serve as documentation of the puzzle format. +Setting Up Your Workstation +===================== + +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, -but if you're advanced enough to have an opinion about nano, -you're advanced enough to know how to use a different editor. +# Animal Time +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 has some tips on how we approach puzzle writing. 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, 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.