Skip to content

tech edits and remove links. #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kknoxrht merged 1 commit into from
May 27, 2026
Merged

tech edits and remove links. #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions modules/ROOT/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,6 @@ By the end of this hackathon, a successful blueprint submission will include:

Ready to start building? We have streamlined the toolchain so you can bypass the formatting hurdles and get straight to the code.

* **Step 1:** Head over to the **xref:start-here/workflow.adoc[AI-Assisted Design Phase]** to put together and generate your course outline from your raw notes and references.
* **Step 2:** Review the **xref:references/asciidocqrg.adoc[AsciiDoc & Antora Cheat Sheet]** to understand how to structure your repository and add formatting flavor to your content.
* **Step 1:** Head over to the **AI-Assisted Design Phase** to put together and generate your course outline from your raw notes and references.
* **Step 2:** Review the **Formatting Cheat Sheet** to understand how to structure your repository and add formatting flavor to your content.
* **Step 3:** Start coding your playbook!
2 changes: 1 addition & 1 deletion modules/references/pages/asciidoc-advanced.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

== Leveling Up Your Blueprints

The xref:toolchain-cheatsheet.adoc[Basic Cheat Sheet] covers everything you need to build a functional playbook. However, if you are documenting complex Red Hat AI Factory deployments, you will likely encounter massive YAML files, long terminal outputs, and dynamic software versions.
The formatting cheat sheet covers everything you need to build a functional playbook. However, if you are documenting complex Red Hat AI Factory deployments, you will likely encounter massive YAML files, long terminal outputs, and dynamic software versions.

Use these advanced AsciiDoc features to make your blueprints highly professional, readable, and easy to maintain.

Expand Down
259 changes: 4 additions & 255 deletions modules/references/pages/asciidocqrg.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
= AsciiDoc & Antora Toolchain Cheat Sheet
:navtitle: Toolchain Cheat Sheet
= AsciiDoc & Antora Cheat Sheet
:navtitle: Formatting Cheat Sheet

== The Goal: Content Over Formatting
When building your AI Factory blueprints, we want you focused on the architecture, not fighting with markup.
Expand Down Expand Up @@ -111,7 +111,7 @@ image::doca-argus-telemetry.png[DOCA Argus Architecture Diagram]
----

**To link to an external site:**
(Always use `window=_blank` so the learner doesn't lose their place in the course!)
(Always use `window=_blank`, open link in a new window, so the learner doesn't lose their place in the course!)
[source,asciidoc]
----
Read the link:https://docs.nvidia.com[NVIDIA Documentation, window=_blank].
Expand All @@ -128,255 +128,4 @@ Check out the xref:troubleshooting-rayclusters.adoc[Troubleshooting Guide].
== Ready? Set. Build.
You have your CDD outline, you understand the repository structure, and you know the AsciiDoc syntax.

**It's time to start coding your blueprint.**

////
= AsciiDoc Quick Reference Guide
:navtitle: AsciiDoc Reference

== Introduction

When building out your playbooks and technical blueprints, you want the focus to remain on the content, not the markup. Use this quick reference guide to handle the most common formatting needs, from basic text styling to embedding rich media and visual callouts.

For deep dives into the syntax, you can always refer to the official https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation,window=_blank] or the https://docs.antora.org/antora/latest/[Antora Documentation,window=_blank].

---

== Basic Text Formatting

Make your text readable by using these standard inline formats:

* **Bold:** `*Text goes here*` renders as *Text goes here*
* **Italics:** `_Text goes here_` renders as _Text goes here_
* **Monospace (Code inline):** `+`Code goes here`+` renders as `Code goes here`
* **Highlight:** `##Text goes here##` renders as highlighted text.

== Headings & Structure

Use equal signs (`=`) to create sections. Remember that a single `=` is reserved for the document title at the top of the page.

[source,asciidoc]
----
== Level 1 Section (Heading 2)
=== Level 2 Section (Heading 3)
==== Level 3 Section (Heading 4)
----

== Lists

Keep your steps clear and concise. Do not nest lists too deeply.

**Bullet Points (Unordered):**
[source,asciidoc]
----
* First item
* Second item
** Sub-item
* Third item
----

**Numbered Steps (Ordered):**
[source,asciidoc]
----
. Step one
. Step two
.. Sub-step
. Step three
----

---

== Visual Callouts (Admonitions)

When you need to draw attention to best practices, security warnings (e.g., STIG requirements), or helpful tips, use admonitions.

[source,asciidoc]
----
NOTE: This is a standard note for general information.

TIP: Use this to share a shortcut or best practice.

IMPORTANT: Use this for crucial information the user must not skip.

WARNING: Use this to warn the user about potential issues.

CAUTION: Use this to advise against actions that could cause data loss or system failure.
----

---


NOTE: This is a standard note for general information.

IMPORTANT: Use this for crucial information the user must not skip.

---

== Code Blocks

Since you are building technical blueprints, you will frequently share code snippets, JSON, or YAML configurations. Wrap your code in four hyphens (`----`) and specify the language for syntax highlighting.

[source,asciidoc]
......
[source,yaml]
----
apiVersion: v1
kind: Pod
metadata:
name: example-pod
----
......

---

== Adding Rich Media (Images, Videos, HTML)

Break up large blocks of text with visual architecture diagrams or instructional videos.

=== Images
Ensure your images are saved in the `images/` directory at the same level as your `.adoc` files.

[source,asciidoc]
----
// Basic image insertion
image::architecture-diagram.png[Architecture Diagram]

// Image with specific formatting (width, alignment)
image::architecture-diagram.png[Architecture Diagram, width=600, align="center"]
----

=== Videos
You can easily embed videos from YouTube or Vimeo to provide visual walk-throughs.

[source,asciidoc]
----
video::dQw4w9WgXcQ[youtube, width=640, height=480]
video::123456789[vimeo]
----

=== Raw HTML Pass-through
If you have a specific HTML embed code (like an interactive terminal or a specialized web component) that AsciiDoc doesn't natively support, you can pass it straight through to the browser.

[source,asciidoc]
----
++++
<iframe src="https://example.com/interactive-widget" width="100%" height="500"></iframe>
++++
----

.example Arcade embed.
++++
<iframe
src="https://demo.arcade.software/pIzuROOj0NbUY4pEHfxN?embed&embed_mobile=inline&embed_desktop=inline&show_copy_link=true"
width="100%"
height="600px"
frameborder="0"
allowfullscreen
webkitallowfullscreen
mozallowfullscreen
allow="clipboard-write"
muted>
</iframe>
++++

== Hard Line Breaks

Sometimes you need to start a new line without creating a completely new paragraph. You can use a hard line break by placing a plus sign (`+`) at the end of the line.

[source,asciidoc]
----
You may also use hard line breaks like this +
for a new line within the paragraph.
----

---

== Links & Cross-References

Connecting your learners to external resources or other parts of your course is crucial for building a cohesive blueprint.

=== External Links
To link to an external website, include the URL followed by the text in brackets. Use `window=_blank` so it opens in a new tab without losing the course page.

[source,asciidoc]
----
Read the https://docs.asciidoctor.org/asciidoc/latest/[official documentation,window=_blank].
----

=== Internal Links (Cross-References)
To link to another page within the same chapter/section, use the `xref:` command.
[source,asciidoc]
----
Check out the xref:faq.adoc[FAQ page] for more details.
----

To link to a page in a completely different section/module, include the module name.
[source,asciidoc]
----
Review the xref:course_guide:course_structure.adoc[Course Structure guide].
----

---

== Tables

Tables are fantastic for comparing hardware benchmarks, organizing STIG requirements, or mapping out parameters.

Here is the syntax for a standard table with a header row:

[source,asciidoc]
......
[cols="2*",options="header"]
|===
|Column 1 Header
|Column 2 Header

|Cell in column 1, row 2
|Cell in column 2, row 2

|Cell in column 1, row 3
|Cell in column 2, row 3
|===
......

---

[cols="2*",options="header"]
|===
|Column 1 Header
|Column 2 Header

|Cell in column 1, row 2
|Cell in column 2, row 2

|Cell in column 1, row 3
|Cell in column 2, row 3
|===

---

== Local Media & Audio

If you are uploading local media files rather than linking out to YouTube or external URLs, you must place the files directly into the `modules/chapterN/images` directory.

*Note: Even audio and video files go into the `images` folder!*

**To reference an image:**
[source,asciidoc]
----
image::sample-image.jpg[]
----

**To reference local video:**
[source,asciidoc]
----
video::video-file.mp4[]
----

**To reference local audio (great for voiceover explanations):**
[source,asciidoc]
----
audio::audio-file.wav[]
----

////
**It's time to start coding your blueprint.**
7 changes: 3 additions & 4 deletions modules/start_here/pages/workflow.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ As an elite engineer, your time during this hackathon is best spent on technical

However, before you start writing AsciiDoc, you need a blueprint. We call this the **Course Design Document (CDD)**. We have an automated script (`skill.md`) that will read this CDD and automatically generate your entire GitHub repository structure, folders, and navigation map for you.

To ensure the automation works, you must use an AI assistant to generate your CDD in a highly specific Markdown format.
To ensure the automation works, we ask that your CDD be in the following specific Markdown format.

== Step 1: The AI Generation Prompt

Copy the prompt below and paste it into your preferred AI assistant (e.g., ChatGPT, Claude, Red Hat Lightspeed) along with your raw technical notes.
The prompt below contains the specific template. You are paste it into your preferred AI assistant (e.g., ChatGPT, Claude, Red Hat Lightspeed) along with your raw technical notes.

[source,text]
----
Expand Down Expand Up @@ -54,10 +54,9 @@ Here are my raw notes:
Once the AI generates your CDD, save it as `prompts/course-design.md` in your repository. Before you run the automation, quickly verify two things:

* **The Table Structure:** Ensure the `Session Type` column strictly uses terms like `Lab` or `Lecture`. This tells the automation which file templates to use.
* **The Infrastructure:** Ensure the `# LAB INFRASTRUCTURE REQUIREMENTS` section accurately reflects your needs (targeting the dual H100 baseline) so the Open Training team can successfully host your playbook.

== Step 3: Auto-Generate Your Repository

With your `course-design.md` file saved, you can now run the initialization script to scaffold your entire course structure automatically!

* **Next Step:** Review the **xref:toolchain-cheatsheet.adoc[AsciiDoc & Antora Cheat Sheet]** to see how to format your code blocks and warnings once you start writing your content.
* **Next Step:** Review the Formating Cheat Sheet ** to see how to format your code blocks and warnings once you start writing your content.
Loading