content editing update

[LolaValente]

Summary by CodeRabbit

• Documentation
  • Major editorial and structural overhaul of the instructor authoring guide for clarity and consistency.
  • Revised headings/styles and reorganized content to foreground Markdown usage and editing workflow (section selection, renaming, hotkeys).
  • Reworked Custom CSS guidance with clearer options and course-level steps.
  • Expanded Markdown editor instructions, formatting reference (headers, lists, code blocks), code-copy behavior, math/LaTeX, collapsibles, callouts, and media embedding.
  • Updated examples, images, and interaction notes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Comprehensive editorial rewrite of source/instructors/authoring/guides/markdown_content.rst: headings and casing normalized, sections reorganized and expanded, prose rewritten into imperative instructions, examples reformatted, and guidance for CSS, Markdown features, MathJax, collapsible content, media, and callouts updated.

Changes

Cohort / File(s)

Summary

Documentation Content Rewrite source/instructors/authoring/guides/markdown_content.rst

Full rewrite and reorganization: normalized heading/title casing; added/renamed subsections (e.g., Selecting Sections in Edit Mode, Editing Hotkeys); shifted tone to imperative voice; restructured Custom CSS section into a descriptive table; expanded Markdown editor guidance and formatting examples (headers, bold/italic, lists, code blocks); clarified copy-to-clipboard behavior and -hide-clipboard usage; expanded Math/LaTeX examples and MathJax notes; clarified collapsible content using <details>/<summary>; standardized callout types and examples; reorganized media/iframe guidance; adjusted images, alt text, anchors, and minor consistency edits.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Review rendered output for each example (code fences, MathJax, collapsible blocks).
• Verify image paths/captions and that copy-to-clipboard behavior and -hide-clipboard are documented correctly.
• Confirm Custom CSS table entries, menu paths (Tools → Guide → Add Custom CSS), and hotkey/navigation descriptions match the UI.

Suggested reviewers

• shajason

Pre-merge checks

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'content editing update' is vague and generic, using non-descriptive language that doesn't convey the specific nature of the changes made to the documentation.	Consider a more descriptive title that highlights the main improvement, such as 'Restructure and expand Markdown content editing guide with improved formatting and examples' or 'Reorganize markdown_content.rst with enhanced CSS and formatting guidance'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6d2e5cf and 788e2a8.

⛔ Files ignored due to path filters (2)

• source/img/guides/inlinemath.png is excluded by !**/*.png, !**/*.png
• source/img/guides/multilinemath.png is excluded by !**/*.png, !**/*.png

📒 Files selected for processing (1)

• source/instructors/authoring/guides/markdown_content.rst (9 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.rst

⚙️ CodeRabbit configuration file

**/*.rst: Review files for:

• Consistent formatting (e.g., headings, lists, links).
• Anywhere there are tables, they should use list-table.
• Clear and concise language.
• Correct grammar and spelling.
• Proper use of rst syntax (e.g., avoid broken links or invalid code blocks).
• Adherence to style guides (e.g., consistent tone, terminology).
  Suggest improvements to enhance readability and accessibility.
• Make sure to find all improvements on the first pass.
  Go through the material multiple times before submitting comments.

Files:

• source/instructors/authoring/guides/markdown_content.rst

🔇 Additional comments (5)

source/instructors/authoring/guides/markdown_content.rst (5)

131-165: Table formatting and content structure look solid.

The list-table implementation here effectively displays different list types with clear examples. The widths and formatting make the content easy to scan.

---

167-225: Code formatting sections are well-organized and clear.

The Code Blocks and Code Segments sections effectively explain syntax highlighting, clipboard behavior, and when to use inline vs. block formatting. The addition of the note at lines 222–223 properly guides users to use code blocks for multi-line content.

---

251-279: Callout Blocks section is well-organized and addresses previous feedback.

The section properly lists available callout types in an accessible inline format, includes a helpful note about the Guidance callout's visibility restrictions, and demonstrates usage with a clear example. The grammar correction (comma after "block" on line 254) is in place.

---

47-47: Verify contextual placement of Play Mode statement.

Line 47 states: "Your content in Play Mode or preview matches the student view exactly." This sentence discusses general preview behavior but appears under the "Custom CSS" section, before CSS instructions. This placement seems contextually misaligned—the statement is about how Guides renders content generally, not about CSS customization specifically.

Consider relocating this statement to an earlier section (e.g., near the "Writing Content" section) where it better fits the narrative flow about how content appears to students, or verify that it belongs here in a revised context about how CSS impacts the preview view.

---

92-104: Markdown section introduction is clear and well-organized.

The section effectively introduces the editor ribbon and provides context for manual markdown users. The heading hierarchy is appropriate and the image placement aids understanding.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

source/instructors/authoring/guides/markdown_content.rst (2)

321-342: Correct capitalization for technical terms: LaTeX and MathJax.

Line 321 uses "Latex" and line 342 uses both "Latex" and "Mathjax". These should be capitalized as "LaTeX" and "MathJax" respectively, which is the standard capitalization for these tools. Apply corrections to:

• Line 321: "Latex is supported using MathJax..." → "LaTeX is supported using MathJax..."
• Line 342: "...for more details on Latex and Mathjax." → "...for more details on LaTeX and MathJax."

---

352-352: Fix RST directive capitalization.

Line 352 uses .. Note:: but RST directives should be lowercase: .. note::. This should be corrected to ensure proper rendering.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bf6d2e1 and 23f017e.

⛔ Files ignored due to path filters (5)

• source/img/Guide_Custom_CSS.png is excluded by !**/*.png, !**/*.png
• source/img/guides/collapsible.png is excluded by !**/*.png, !**/*.png
• source/img/guides/editnav.png is excluded by !**/*.png, !**/*.png
• source/img/guides/editor-ribbon.png is excluded by !**/*.png, !**/*.png
• source/img/guides/mathjax.png is excluded by !**/*.png, !**/*.png

📒 Files selected for processing (1)

• source/instructors/authoring/guides/markdown_content.rst (12 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.rst

⚙️ CodeRabbit configuration file

**/*.rst: Review files for:

• Consistent formatting (e.g., headings, lists, links).
• Anywhere there are tables, they should use list-table.
• Clear and concise language.
• Correct grammar and spelling.
• Proper use of rst syntax (e.g., avoid broken links or invalid code blocks).
• Adherence to style guides (e.g., consistent tone, terminology).
  Suggest improvements to enhance readability and accessibility.
• Make sure to find all improvements on the first pass.
  Go through the material multiple times before submitting comments.

Files:

• source/instructors/authoring/guides/markdown_content.rst

🔇 Additional comments (1)

source/instructors/authoring/guides/markdown_content.rst (1)

355-356: Review backtick formatting in note section for RST rendering.

Lines 355-356 contain backticks within the note that reference markdown syntax ( `js and ```). The formatting may not render properly in RST. Consider using literal blocks or adjusting the syntax escaping to ensure the note displays correctly for users.

For example, line 355 reads: "All code block starter lines, e.g. ```js must be preceded by a blank line." The backticks may not display as intended.

[coderabbitai]

Actionable comments posted: 5

♻️ Duplicate comments (2)

source/instructors/authoring/guides/markdown_content.rst (2)

123-123: Fix grammatical phrasing to use "on either side" instead of "either side."

Line 123 reads: "To create bold or italic text, you use ** and * either side of the text." The phrase "either side" is incomplete; it should be "on either side" for grammatical correctness.

-To create bold or italic text, you use `**` and `*` either side of the text.
+To create bold or italic text, use `**` and `*` on either side of the text.

---

211-211: Add missing period at sentence end.

Line 211 is missing terminal punctuation. The sentence should end with a period after the backticks.

-If you wish to suppress the 'copy to clipboard' button in the code block, append ```-hide-clipboard``` to the first line.
+If you wish to suppress the 'copy to clipboard' button in the code block, append ```-hide-clipboard``` to the first line.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 23f017e and 1c87e72.

📒 Files selected for processing (1)

• source/instructors/authoring/guides/markdown_content.rst (11 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.rst

⚙️ CodeRabbit configuration file

**/*.rst: Review files for:

• Consistent formatting (e.g., headings, lists, links).
• Anywhere there are tables, they should use list-table.
• Clear and concise language.
• Correct grammar and spelling.
• Proper use of rst syntax (e.g., avoid broken links or invalid code blocks).
• Adherence to style guides (e.g., consistent tone, terminology).
  Suggest improvements to enhance readability and accessibility.
• Make sure to find all improvements on the first pass.
  Go through the material multiple times before submitting comments.

Files:

• source/instructors/authoring/guides/markdown_content.rst

[coderabbitai]

Actionable comments posted: 3

♻️ Duplicate comments (3)

source/instructors/authoring/guides/markdown_content.rst (3)

123-123: Refine awkward phrasing for improved readability.

The phrasing "you use ** and * either side of the text" is still awkward. The past review correctly identified this should read "on either side" for better clarity.

- To create bold or italic text, you use `**` and `*` either side of the text.
+ To create bold or italic text, use `**` and `*` on either side of the text.

---

211-211: Add missing terminal punctuation.

Line 211 ends with "append -hide-clipboard to the first line" but is missing a period.

- If you wish to suppress the 'copy to clipboard' button in the code block, append ```-hide-clipboard``` to the first line.
+ If you wish to suppress the 'copy to clipboard' button in the code block, append ```-hide-clipboard``` to the first line.

---

342-342: Improve reference placement and punctuation for clarity.

Line 342 has a period before the Sphinx reference, creating an awkward pause: "...like this: $\omega = d\phi / dt$. :ref:For more information...." The structure breaks the flow of the sentence.

- Inline math equations are encapsulated in a single `$` like this: $\omega = d\phi / dt$. :ref:`For more information on LaTeX and MathJax <latex>`.
+ Inline math equations are encapsulated in a single `$` like this: $\omega = d\phi / dt$ — :ref:`learn more about LaTeX and MathJax <latex>`.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1c87e72 and 6d2e5cf.

📒 Files selected for processing (1)

• source/instructors/authoring/guides/markdown_content.rst (11 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.rst

⚙️ CodeRabbit configuration file

**/*.rst: Review files for:

• Consistent formatting (e.g., headings, lists, links).
• Anywhere there are tables, they should use list-table.
• Clear and concise language.
• Correct grammar and spelling.
• Proper use of rst syntax (e.g., avoid broken links or invalid code blocks).
• Adherence to style guides (e.g., consistent tone, terminology).
  Suggest improvements to enhance readability and accessibility.
• Make sure to find all improvements on the first pass.
  Go through the material multiple times before submitting comments.

Files:

• source/instructors/authoring/guides/markdown_content.rst