====== DokuWiki Help Authoring Guide - DW Edit Wiki Markup ======

===== Scope and Outcome =====

This guide covers the same article lifecycle as the visual guide, but from DW Edit mode. It includes syntax-safe patterns for headings, lists, media, links, callouts, related topics, and revision control.

===== Access and Setup =====

  - Sign in with edit rights and open a reference page in the target namespace. \\ [[dwiki_setup_001.png:Signed-in article view with namespace path and page tools visible.]]
  - Open Create Page from Page Tools when creating new content. \\ [[dwiki_setup_002.png:Create Page entry highlighted in page tools menu.]]
  - For existing content updates, open Edit and set mode=dwiki. \\ [[dwiki_setup_003.png:URL and mode selector showing ''mode=dwiki'' with source textarea visible.]]
  - Enable line numbers or monospaced view if your editor skin supports it. \\ [[dwiki_setup_004.png:DW Edit text area with line number gutter visible.]]

===== Create a New Page (DW Edit Path) =====

  - In Create Page, select Sidebar Location node where the page belongs. \\ [[dwiki_create_005.png:Sidebar tree with selected node and nearby siblings for context.]]
  - Set placement mode (Nested/Before/After) to control nav order. \\ [[dwiki_create_006.png:Insert mode dropdown expanded and selected option boxed.]]
  - Enter Page ID using clean token rules (no spaces, prefer lowercase + underscores). \\ [[dwiki_create_007.png:Page ID input with valid sample and invalid examples annotated.]]
  - Enter Page Title for the H1 heading. \\ [[dwiki_create_008.png:Page title field and note that it generates the starting H1 text.]]
  - Set Open in Editor = DW Edit (text). \\ [[dwiki_create_009.png:Editor mode dropdown with DW Edit selected.]]
  - Create the page and verify redirect to raw markup editor. \\ [[dwiki_create_010.png:DW Edit source textbox opened with starter H1 line at top.]]

===== Core Markup Patterns (Use Exactly) =====

Heading syntax:
  * H1: ====== Article Title ======
  * H2: ===== Section =====
  * H3: ==== Subsection ====
  * H4: === Detail ===
Text emphasis:
  * Bold: **text**
  * Italic: //text//
  * Underline: __text__
  * Monospace/code inline: ''text''
List patterns:
  * Ordered step: two spaces + dash + space => '' - Step text''
  * Nested bullet under a step: four spaces + star + space => '' * Detail''
  * Keep list clusters tight; avoid empty lines that split flow.
Image/link patterns:
  * Internal article link: [[namespace:pageid]]
  * Link with custom label (only when needed): [[namespace:pageid|Readable Label]]
  * Image: {{namespace:image.png|caption}}
  * Step + image continuation on same line: '' - Action text \\ {{namespace:image.png|caption}}''

===== Write Procedural Content in DW Edit =====

  - Keep one H1 at top; begin task sections with H2 headings. \\ [[dwiki_procedure_011.png:DW Edit source showing H1 and first H2 lines with syntax highlighted.]]
  - Start each user action as a numbered-step list item ('' -''). \\ [[dwiki_procedure_012.png:Source lines with ordered steps and visible indentation marks.]]
  - Attach screenshot refs directly in-step using ''\'' line breaks. \\ [[dwiki_procedure_013.png:Single step line showing action + ''\'' + image token in one logical line.]]
  - Attach callouts in-step (Note/Warning/etc.) using another ''\'' segment. \\ [[dwiki_procedure_014.png:Step line containing action, image token, and warning sentence separated by ''\''.]]
  - For non-sequential details of one step, add nested bullets indented under that step. \\ [[dwiki_procedure_015.png:Step followed by indented ''*'' bullet lines (4 spaces) in source view.]]
  - Do not insert blank lines between a step, its nested bullets, and the next step when continuity matters. \\ [[dwiki_procedure_016.png:Side-by-side good vs bad source snippet with blank-line regression highlighted.]]
  - Reserve heading syntax for real sections only; do not use headings as callouts. \\ [[dwiki_procedure_017.png:Example of wrong ''== callout =='' replaced with inline ''Warning:'' text.]]

===== Add and Maintain Related Topics (DW Edit Standard) =====

  - At the end of the article, add heading exactly: ''==== Related Topics ====''. \\ [[dwiki_related_018.png:End-of-article source with exact Related Topics heading boxed.]]
  - List one internal link per line under that heading. \\ [[dwiki_related_019.png:Related topic block with one clean internal link on each line.]]
  - Do not duplicate a target with both plain and labeled link variants. \\ [[dwiki_related_020.png:Bad duplicate example lines crossed out; good single line kept.]]
  - Prefer ''[[namespace:pageid]]'' format unless explicit label override is required. \\ [[dwiki_related_021.png:Example conversion from labeled/bolded link to clean page-id-only link.]]
  - Check for ''.html'' style legacy links and convert to internal page IDs when possible. \\ [[dwiki_related_022.png:Source snippet with old html-like target and corrected internal target.]]

===== Edit Existing Articles in DW Edit =====

  - Open existing article in DW Edit mode and scan full source before changing anything. \\ [[dwiki_edit_023.png:Large source textarea with scroll indicators and key anchors marked.]]
  - Locate target section by heading and confirm surrounding list structure. \\ [[dwiki_edit_024.png:Search/highlight in source showing heading and nearby list lines.]]
  - Apply edits without reflowing unrelated whitespace around stable sections. \\ [[dwiki_edit_025.png:Edited chunk with untouched adjacent lines annotated.]]
  - After list edits, manually verify indent counts on every list line. \\ [[dwiki_edit_026.png:Visible whitespace/indent guide showing 2-space and 4-space patterns.]]
  - After image edits, confirm each media token resolves in correct namespace. \\ [[dwiki_edit_027.png:Media token lines with namespace prefixes boxed and compared.]]
  - Run Preview and inspect rendered list continuity and image placement. \\ [[dwiki_edit_028.png:Preview rendering with source pane still visible for cross-checking.]]

===== Revision Management and Rollback =====

  - Before major changes, copy a temporary local snapshot of the current source block. \\ [[dwiki_revision_029.png:Source text selected and copied to temporary note file for safety.]]
  - Enter clear revision summary on every save. \\ [[dwiki_revision_030.png:Revision summary field with example: 'Updated restore workflow images and corrected step sequencing'.]]
  - Open Revisions and compare old/new versions after publish. \\ [[dwiki_revision_031.png:Revisions page with two versions selected and compare action highlighted.]]
  - If formatting regressed, restore known-good revision and then reapply only targeted edits. \\ [[dwiki_revision_032.png:Restore flow with warning dialog and safe reapply plan callout.]]
  - Document rollback reason in next summary for audit clarity. \\ [[dwiki_revision_033.png:Follow-up summary note showing rollback explanation.]]

===== Comprehensive DW Edit Feature Matrix =====

  * Headings: H1-H4 with strict hierarchy.
  * Text formatting: bold, italic, underline, monospace.
  * Lists: ordered workflow lines ('' -'') and nested bullets ('' *'').
  * Line breaks: ''\'' for attaching notes/images/callouts to steps.
  * Links: internal, labeled internal, external (with caution).
  * Media: namespace-based image embedding with captions.
  * Tables: wiki table syntax for reference matrices.
  * Code: ''<code>...</code>'' for command/config examples.
  * Callouts: inline Note/Warning/Info/Tip text, not decorative headings.
  * Related Topics: one link per line, no duplicate targets.
  * Revisions: summary discipline, compare, restore, and post-restore verification.

===== High-Detail Screenshot Placeholder Conventions =====

  - Every procedural step should have at least one placeholder directly below it. \\ [[dwiki_capture_034.png:Document excerpt showing step followed immediately by placeholder token.]]
  - Use filenames that map to section + sequence (example: dwiki_edit_042.png). \\ [[dwiki_capture_035.png:Folder screenshot with filename ordering and one-to-one placeholder mapping.]]
  - Write placeholder descriptions so an annotator can place arrows without asking follow-up questions. \\ [[dwiki_capture_036.png:Placeholder text example with explicit control names, location cues, and intended emphasis.]]
  - Call out where numbered stamps should appear in multi-click images. \\ [[dwiki_capture_037.png:Composite UI screenshot with suggested stamp positions 1,2,3 indicated in description.]]
  - Call out where bounding boxes should isolate dialogs, warnings, and final save controls. \\ [[dwiki_capture_038.png:Example screenshot annotated with box regions referenced by description text.]]

==== Related Topics ====
[[documentation:help_article_authoring_dwedit_wiki_markup]]
[[documentation:help_article_authoring_visual_editor]]