DokuWiki Help Authoring Guide - Visual Editor

This guide trains an editor to create a new help article, maintain existing content, and manage revisions using the Visual Editor. All screenshot placeholders are intentionally detailed for downstream arrow/box/stamp annotation. Output standards required by this guide:

• Single H1 per article.
• Clear heading hierarchy (H2/H3/H4) with no decorative heading misuse.
• Step lists remain continuous without accidental restart.
• Images are attached to the step line intent and context.
• Related Topics uses one internal link per line and no duplicate targets.
• Every significant save includes a revision summary.

1. Sign in with an account that has edit permissions for the target namespace.
   Browser on DokuWiki login page with username field, password field, and sign-in button. Add arrow to currently active user profile indicator after login.
2. Open the destination article or a nearby article in the same namespace to confirm visibility of the Page Tools menu.
   Article view with Page Tools panel visible. Highlight both article title area and page-tools area.
3. Confirm the Create Page tool is visible in Page Tools.
   Page Tools expanded, with Create Page entry boxed and arrow stamp indicating where to click.
4. Confirm you can open Visual Edit mode from the current page.
   Edit controls showing Visual Edit option. Include pointer over the Visual mode selector.
5. If the page is locked by another editor, wait or coordinate before proceeding.
   Lock notice/banner visible. Box lock message text and include callout of lock owner/timestamp if shown.

Use the Create Page tool so page ID, heading, sidebar placement, and editor mode are configured in one flow. This prevents orphan pages and reduces post-save navigation fixes.

1. From the source or parent article, click Create Page in Page Tools.
   Page view with Create Page tool highlighted. Include a red box around Create Page and an arrow from upper-right pointing down.
2. In Sidebar Location, choose the exact navigation node where the new article belongs.
   Create Page dialog with sidebar tree expanded. Box the selected node and show sibling nodes for context.
3. Set Placement Relative to Selected Section (Nested, Before, or After) based on navigation intent.
   Insert mode dropdown open showing Nested/Before/After. Add annotation describing selection rationale.
4. If required, enter New Subnamespace Path for deeper categorization.
   requiredsetupsteps. Highlight colon-separated format.
5. Enter Page ID using lowercase, underscores where needed, and no spaces.
   Page ID field with valid and invalid examples side-by-side annotation.
6. Enter Page Title (H1 heading) exactly as the human-facing article name.
   Page Title field with final title text selected. Box this field and call out 'controls article H1'.
7. Optionally set Sidebar Menu Label only when it must differ from title for navigation readability.
   Sidebar label field with note showing when left blank it defaults from title.
8. Choose Open New Page in Editor = Visual Edit (WYSIWYG).
   Editor mode dropdown open with Visual Edit selected and DW Edit option visible below.
9. Leave Insert/Update in Sidebar checked unless creating a hidden or temporary page.
   Checkbox row showing add-to-sidebar option checked. Add callout about standard behavior.
10. If your workflow uses context redirects, toggle Generate Context ID; otherwise leave it off.
    Generate context ID checkbox and helper text visible. Highlight optional nature.
11. Click Create Page.
    Create button pressed state with spinner/loading indicator if present.
12. Verify immediate redirect to the new article in Visual Edit mode.
    New blank article opened in visual editor with title bar and editable body area boxed.

1. Insert one H1 only at top (already created by Create Page flow); do not add a second H1.
   Visual editor content area showing title and heading style dropdown. Box H1 control and current heading.
2. Create H2 sections for major procedures and H3/H4 for subsections.
   Heading dropdown expanded with Heading 2/3/4 options and sample selected paragraph.
3. Draft a short purpose statement below H1 before procedural steps.
   Top paragraph under title with sentence-level box and annotation for expected length (1-3 lines).
4. Use numbered lists for sequence-critical tasks.
   Numbered list toolbar button highlighted and first two steps visible in body.
5. Use bullet lists only for non-sequential options/details.
   Bulleted list under a numbered step rendered as nested details. Box indentation controls.
6. Avoid blank paragraphs inside a numbered workflow to prevent visual ambiguity.
   warning annotation included.
7. For in-step callouts, keep explanatory note attached to the step content rather than separate heading blocks.
   A numbered step with inline note sentence. Arrow pointing to attached callout text region.

1. Apply Bold only to UI labels, key actions, and critical warnings.
   Text selection with bold button active. Box both selected words and toolbar bold icon.
2. Use Italic sparingly for emphasis, not for normal procedural text.
   Italic toggle in toolbar with sample phrase and annotation on limited use.
3. Use underline only when your style guide explicitly calls for it.
   Underline button visible but callout warns against overuse.
4. Use strikethrough only for deprecated paths or historical references.
   Strikethrough example line with annotation 'deprecated path only'.
5. Use undo/redo immediately when format drift appears.
   Undo/redo controls boxed with before/after mini callouts in content area.
6. Use remove-format or clear-style tools when pasted content brings unwanted styles.
   Pasted paragraph with mixed styling and clear-format action highlighted.
7. Insert horizontal rules only between major sections, not between every step group.
   Horizontal line in editor with annotation for proper placement.
8. Use tables for matrix/reference data, not linear task procedures.
   Table insert menu and sample 3-column reference table in article body.

1. Use internal links for same-wiki articles whenever possible.
   Link dialog showing internal page selection/search with target article chosen.
2. When linking to a specific section, verify anchor resolves after save.
   Link dialog anchor field filled and preview of target section shown.
3. Use external links only for authoritative outside destinations.
   External URL field with protocol visible and note about verified domains.
4. At the end of the article, create the heading exactly as ==== Related Topics ====.
   End-of-article view with Related Topics heading typed exactly and boxed.
5. Under Related Topics, place one internal wiki link per line.
   Related Topics list area showing clean one-link-per-line block.
6. Do not duplicate the same page target with two variants.
   Comparison callout showing bad duplicate pair vs good single link format.
7. Do not use bold labels inside Related Topics links unless explicitly required.
   **Label**) to (page) with annotation.

1. Place cursor exactly where the screenshot belongs in step context before inserting media.
   Cursor indicator directly inside numbered step line where image should attach.
2. Open Media Manager/Insert Image from toolbar.
   Media manager modal open with toolbar insert-image button highlighted.
3. Select the correct namespace folder matching article scope.
   Media tree on left with target namespace highlighted and sibling folders visible.
4. Upload or choose existing image with a clear, stable filename.
   Upload area showing file picker plus selected filename with naming convention callout.
5. Set image size intentionally for readability (avoid tiny/blurry output).
   Image settings dialog with width parameter field boxed and preview panel visible.
6. Add descriptive alt/caption text where applicable.
   Caption or alt-text field filled with explicit UI description.
7. After insertion, ensure image remains attached to relevant step text.
   Rendered step line with image positioned and annotation arrow connecting text and image.
8. Avoid remote hotlinked images for long-term reliability.
   Example of external URL image source crossed out, local media link boxed as preferred.

1. Open the target article and switch to Visual Edit mode.
   Article read view and transition to visual mode shown with mode selector boxed.
2. Read the full article once before editing to identify structure and cross-link dependencies.
   Scrollable article with markers on key sections to review before change.
3. Locate the exact section to modify and keep heading hierarchy unchanged unless requested.
   Section heading and subsection relationship boxed with hierarchy callout.
4. Apply text changes in small coherent chunks and re-check formatting after each chunk.
   Edited paragraph with nearby unchanged paragraph for comparison.
5. When modifying step procedures, verify numbered sequence continuity from start to finish.
   arrows show list progression.
6. If adding new screenshots, insert them at the precise step and update surrounding wording.
   Before/after step comparison with new image insertion location boxed.
7. Update Related Topics only when scope changes or new sibling articles are relevant.
   Related Topics section with one new link added and duplicate removed.

1. Use Preview before final save when touching list structures, headings, or images.
   Preview pane and editor pane split with changed region highlighted.
2. Enter a revision summary describing what changed and why.
   Summary field near save controls filled with concise but specific summary text.
3. Save the page and wait for full render.
   Save button pressed and post-save rendered page visible.
4. Re-open the article in read mode and verify: headings, list continuity, images, links, and related topics.
   Published article with QA checklist callouts around each validation area.
5. Open at least two related linked pages to confirm no broken navigation.
   Two browser tabs with linked pages loaded and status checks annotated.

1. Open Revisions for the article from page tools.
   Revisions entry in page tools boxed and clicked.
2. Select two revisions and run a side-by-side diff.
   Diff screen with added/removed content colors boxed and legend highlighted.
3. Verify whether a regression was introduced (list resets, wrong heading levels, bad links).
   Diff view callouts pinpointing formatting regressions.
4. Restore a prior revision only after confirming it resolves the issue and does not drop valid updates.
   Restore confirmation control and warning text highlighted.
5. After restore, add a new revision summary documenting why rollback was done.
   Post-restore edit summary with rationale text entered.

• Heading levels (H2/H3/H4), paragraph style, bold/italic/underline/strike.
• Numbered and bulleted lists, nesting controls, indent/outdent.
• Internal/external links, anchor links, unlink/edit-link.
• Media manager insert, image sizing, caption/alt text.
• Table insert/edit, row/column add/remove, alignment.
• Horizontal rule, special characters, clear formatting.
• Undo/redo, preview, save summary, revisions compare/restore.

1. Capture full-page context first, then tight crop around the exact control used in each step.
   full context screenshot and detail crop screenshot with matching IDs.
2. Keep cursor visible when instruction references precise placement.
   Cursor positioned in text line where image insertion or edit happens.
3. Leave enough whitespace around dialogs for callout boxes and arrow labels.
   Dialog screenshot with margin guides drawn to show annotation-safe area.
4. Use consistent resolution and zoom so arrow positions remain predictable across steps.
   Browser zoom indicator and image dimensions panel shown with approved setting.
5. Name screenshots to match placeholder IDs exactly for automated substitution.
   Folder listing where filenames match placeholder tokens one-to-one.

DokuWiki Help Authoring Guide - Visual Editor DokuWiki Help Authoring Guide - DW Edit Wiki Markup