Update documentation for mr4

404.html

@@ -5,31 +5,33 @@
 
 <style>
   main {
+    grid-column: full;
     margin: 0 auto;
+    padding: 6rem 1.25rem;
     text-align: center;
-    grid-column: full;
   }
-  h1 {
-    font-size: 4em;
-    margin-bottom: 0;
+  main h1 {
+    font-size: 4rem;
+    margin-bottom: 0.5rem;
   }
-  p {
-    margin: 0;
+  main p {
+    color: var(--mr-text-muted);
+    margin: 0 0 1.5rem;
   }
 </style>
 
 <main id="content">
   <h1>404</h1>
   <p>The requested page could not be found</p>
+  <p><a href="/">Browse the documentation</a></p>
 </main>
 
 <script type="module">
-// URLs on the old site started with /en-us/ which isn't a valid locale;
-// we'll redirect these to the correct /en-US/ so that old links don't break.
-if (window.location.pathname.startsWith("/en-us/")) {
-  window.location.replace(window.location.pathname.replace("/en-us/", "/en-US/"));
-} else if (window.location.pathname.startsWith("/documentation/")
-  || window.location.pathname.startsWith("/screencasts/")) {
-  window.location.replace('/en-US' + window.location.pathname);
+// The site used to live under a locale segment, e.g. /en-US/documentation/page/
+// (and older links used the invalid /en-us/). Send those to the flat URL so
+// existing links and bookmarks keep working.
+const match = window.location.pathname.match(/^\/en-[Uu][Ss](\/.*)?$/);
+if (match) {
+  window.location.replace((match[1] || "/") + window.location.hash);
 }
 </script>

README.md

@@ -4,7 +4,6 @@ Documentation site for MapRoulette.org
 
 If you would like to contribute to this documentation, thank you!
 * If you want to fix a typo, update something that's out-of-date, or add a page or section on a new topic, please feel free to open a PR. Though if you want to add a new page or make large changes to existing content, you should probably open an issue first to gather feedback on your proposed changes.
-* If you'd like to help translate existing documentation into other languages, have a look at our [guide on how to contribute translations](https://learn.maproulette.org/en-US/documentation/translate-docs/).
 * If you have a video or article we should link to, feel free to open an issue and we will look at the best way to include it.
 
 ## Technical Details

SCREENSHOTS-TODO.md

@@ -0,0 +1,46 @@
+# Screenshots to re-shoot
+
+The prose in `_documentation/` has been brought in line with the current
+MapRoulette frontend, but **no images were replaced**. Screenshots of UI that no
+longer exists were removed from the pages rather than left in place, since a
+picture of a screen the reader can't find is worse than no picture. Everything
+removed is listed here so it can be re-shot and dropped back in; the files
+themselves are all still in `media/`.
+
+Pages marked _legacy_ carry a callout saying the feature isn't in the current
+frontend. Those keep their old screenshots deliberately — they illustrate how
+the feature used to work — and should only change if the feature returns.
+
+| Page | Removed | What a replacement should show |
+|:-----|:--------|:-------------------------------|
+| `getting-started/02-discovering-challenges` | `sorting-1`…`sorting-8` | The Explore Challenges filter bar: location search, Sort by, Work on, Difficulty, Global, Clear filters, and the three view-mode buttons. Plus the grid-with-map result view. |
+| `advanced/02-markdown` | `markdown_preview.jpg` | Markdown source beside its rendered output, using only CommonMark features (the old shot used a GFM table, which no longer renders). |
+| `user-settings/02-setting-your-map-base-layer` | `66154078-…`, `setting-default-baselayer2` | The **Map style** control open on a task map, showing the five bundled base layers. |
+| `challenges/08-reporting-a-challenge` | `screen-shot-2021-03-02-…` ×2 | The challenge header's **Comments** button, and the "by _username_" link through to the owner's OSM profile. |
+| `mapping/03-solving-multiple-tasks-together` | `66520790-…`, `66521253-…`, `66521347-…`, `66521469-…` | The **Work on multiple tasks** panel with a few tasks selected, and the bundled task list on the Task tab. |
+| `challenges/01-creating-a-challenge` | `create-challenge-1`…`create-challenge-4` | The challenge form (project picker, basic info, challenge image, task data, code-of-conduct agreement), and the challenge page after tasks finish building. |
+| `tasks/03-setting-external-task-identifiers` | `setting_external_id_field` | Nothing — the setting has no UI. Leave imageless. |
+| `challenges/10-exporting-challenge-data` | `export_challenge_data` | **Export CSV** on a project's actions menu under Manage → Projects. |
+| `tasks/07-bulk-editing-challenges` | `bulk-edit-1`…`bulk-edit-4` | Task rows selected in a challenge's task table with the bulk actions toolbar showing, and one of its confirmation dialogs. |
+| `challenges/07-challenge-comments` | `challenge-comments-2` | The **Comments** button in the challenge header and the Challenge Comments dialog, with **Show task comments** checked. |
+| `challenges/09-challenge-flagging` | `challenge-flagging-1`…`challenge-flagging-5` | The **Challenge actions** menu with **Report Challenge**, the report dialog, the **Challenge Reported** state afterwards, and the Super Admin → Challenge Reports queue. |
+| `mapping/02-rapid-editor` | `rapid-editor-1` | The built-in iD editor open in the task screen, with its Re-Center / Select Tasks / Focus / Close editor bar. |
+| `getting-started/01-your-dashboard` | `dashboard-1`…`dashboard-7` | The three-column dashboard: Saved Challenges, profile and level, Contributions + Locked Tasks + Teams. Plus the Mapper Level System dialog. |
+| `projects/01-projects-and-project-managers` | `projects-project-managers-1`, `-2` | Manage → Projects, and a project's page with its challenge list and Project Playbook. |
+| `not-implemented/02-reviewing` | `reviewing-1`…`reviewing-6` | Nothing to re-shoot while reviewing is unavailable, beyond the Reviews Received / Reviews Performed blocks on a profile. |
+| `tasks/02-using-maproulette-tags` | `mr-tags-1`…`mr-tags-13` (kept `bad-imagery`, `mr-tags-10`, `mr-tags-11`) | The **Edit task tags** dialog with "Popular in this challenge" chips, and the **Tags (Optional)** field in the completion dialog. |
+| `mapping/01-using-layouts` _(legacy)_ | `all_the_widgets`, `edit_layout_control`, `export_layout`, `import_layout`, `laying_out_workspace.gif`, `layout_dropdown` | The page is now about the task screen's two resizable panels and its four tabs. Needs one shot of that. |
+
+## Pages that could use a screenshot but never had one
+
+- `advanced/01-using-keyboard-shortcuts` — the **Keyboard Shortcuts** dialog (<kbd>?</kbd>).
+- `user-settings/03-notifications-and-email` — the Notifications page with its filters, saved views and thread pane.
+- `getting-started/04-point-scoring` — the Mapper Level System dialog.
+- `tasks/01-task-priority-rules` — the prioritization editor with its tier tabs, match counts and preview map.
+- `teams/01-teams` — the Teams page with a pending invitation, and a team's page with its members and challenge images.
+
+## Elsewhere
+
+- `index.md` (the landing page) still uses `welcome-index.png`, which
+  shows the previous interface. Replace with a shot of the current Explore
+  Challenges page.

_config.yaml

@@ -11,26 +11,31 @@ collections:
     output: true
 
 
-# list of enabled (translated) locales
-locales:
-  - en-US
-  # - de-DE
-  # - es
-  # - fr-FR
-  # - nl
-  # - pt-PT
-  # - ru
-
-# specifies the order of sections in the sidebar. each entry should match the
-# name of a directory in _docs
+
+# Order of the sidebar sections. Each entry must match a directory name under
+# _documentation/.
 sections:
-  - new-topics
-  - basics
-  - advanced
-  - creating-challenges
+  - getting-started
+  - migrating
+  - mapping
+  - user-settings
+  - projects
+  - challenges
+  - tasks
   - teams
+  - advanced
   - server-admin
-
+
+# Pages offered in the search box before anything has been typed. Listed by
+# slug; the title and section label are looked up from the page itself, so they
+# stay correct if a page is retitled or moved.
+recommended_pages:
+  - discovering-challenges
+  - your-dashboard
+  - creating-a-challenge
+  - using-keyboard-shortcuts
+  - teams
+
 defaults:
   - scope: { path: "" } # empty string matches all files in the project
     values:
@@ -40,4 +45,5 @@ exclude:
   - CODE_OF_CONDUCT.md
   - LICENSE.md
   - README.md
+  - SCREENSHOTS-TODO.md
   - mise.toml

_data/sections.json

@@ -0,0 +1,12 @@
+{
+  "getting-started": "Getting Started",
+  "migrating": "Migrating from MR3",
+  "mapping": "Mapping Tasks",
+  "user-settings": "User Settings",
+  "projects": "Projects",
+  "challenges": "Challenges",
+  "tasks": "Tasks",
+  "teams": "Teams",
+  "advanced": "Advanced",
+  "server-admin": "Server Admin"
+}

_documentation/advanced/01-using-keyboard-shortcuts.md

@@ -0,0 +1,46 @@
+---
+title: Using Keyboard Shortcuts
+---
+
+A number of keyboard shortcuts are available while you're working on a task.
+The current list is always available in the app itself: press <kbd>?</kbd> on
+the task screen to open the **Keyboard Shortcuts** dialog, which shows only the
+shortcuts that apply to what you're doing right now, grouped by category.
+
+At the time of writing, the following shortcuts are available.
+
+### Task actions
+
+| Key                                          | Action                          |
+| :------------------------------------------- | :------------------------------ |
+| <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>F</kbd>  | Mark as Fixed [^1]              |
+| <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>P</kbd>  | Mark as False Positive / Not an Issue [^1] |
+
+### Map
+
+| Key             | Action                                                |
+| :-------------- | :---------------------------------------------------- |
+| <kbd>H</kbd>    | Show or hide all task markers                         |
+| <kbd>F</kbd>    | Show only the tasks you're working on [^2]            |
+| <kbd>Esc</kbd>  | Cancel drawing [^3]                                   |
+
+### Multi-task
+
+| Key                | Action                                            |
+| :----------------- | :------------------------------------------------ |
+| <kbd>D</kbd>       | Start drawing to add tasks to your selection      |
+| <kbd>Delete</kbd>  | Leave multi-task mode and work on the primary task only [^2] |
+
+### Anywhere in MapRoulette
+
+| Key                                          | Action                          |
+| :------------------------------------------- | :------------------------------ |
+| <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>K</kbd>  | Open the search box             |
+| <kbd>?</kbd>                                 | Show the keyboard shortcuts dialog (task screen) |
+
+[^1]: Only available once you have locked the task, and not while the challenge is paused or a dialog is open.
+[^2]: Only available while you have more than one task selected.
+[^3]: Only available while you are drawing.
+
+Shortcuts are ignored while you're typing in a text box, so you can write a
+comment containing an `f` or a `?` without triggering anything.

_documentation/advanced/02-markdown.md

@@ -0,0 +1,40 @@
+---
+title: Styling Text with Markdown
+---
+
+MapRoulette supports Markdown for marking up or styling text. Markdown can be
+used in most places where long-form text can be entered, such as task comments,
+challenge comments, challenge descriptions and challenge instructions.
+
+## What's supported
+
+MapRoulette renders [CommonMark](https://commonmark.org/), with one
+MapRoulette-specific addition: **a single newline is rendered as a line
+break**, so text looks the way it did in the box you typed it into rather than
+being reflowed into one paragraph. If you want two lines to run together,
+remove the line break in your source text.
+
+That covers the everyday things:
+
+- headings (`# Heading`)
+- **bold** (`**bold**`) and _italic_ (`_italic_`)
+- links (`[text](https://example.com)`) — bare URLs in descriptions and
+  instructions are turned into links automatically
+- bulleted and numbered lists
+- `inline code` and fenced code blocks
+- block quotes
+- images
+
+## What isn't
+
+- **Raw HTML.** Unlike GitHub-flavored Markdown, MapRoulette does not render
+  HTML embedded in Markdown; it is dropped.
+- **GitHub extensions.** Tables, strikethrough, task list checkboxes and
+  footnotes are GFM additions rather than CommonMark, and are not rendered. If
+  you have older challenge text that relies on a Markdown table, it will appear
+  as literal pipes and dashes — reach for a list instead.
+
+## Mentions
+
+Writing `@username` in a comment links to that user and notifies them. See
+[Short-codes in Comments](/documentation/comment-short-codes/).