From 7fd352dbee048cf7bd0a09a58747978d508acfcb Mon Sep 17 00:00:00 2001 From: Katie McCormick Date: Tue, 21 Apr 2026 12:51:38 -0700 Subject: [PATCH 1/4] add adding courses guide --- README.md | 1 + adding-courses.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 adding-courses.md diff --git a/README.md b/README.md index 1b902c9a824..865def8abad 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Refer to: - Our [MDX guide](./mdx-guide.md) for how to write documentation and use our variant of markdown. - Our [style guide](./style-guide.md) for technical writing guidance. +- The [adding courses guide](./adding-courses.md) for a step-by-step guide to add a new course to Learning. ### Licensing diff --git a/adding-courses.md b/adding-courses.md new file mode 100644 index 00000000000..5001039a88b --- /dev/null +++ b/adding-courses.md @@ -0,0 +1,92 @@ +# Adding courses to Qiskit/documentation + +This guide walks through the full process of adding a course to the documentation site. + +This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via [NVM](https://github.com/nvm-sh/nvm)), [tox](https://pipx.pypa.io/stable/) (via pipx), and [Rancher Desktop](https://rancherdesktop.io/) installed. + +1. Make a new folder for the course under `/learning/courses`. The name of this folder will be the slug of the course on the website. For example, `/learning/courses/my-course` will have the URL https://quantum.cloud.ibm.com/learning/my-course. + +2. Add your notebooks to this folder. + + > :warning: **Warning:** + > Make sure there are no capital letters in your filenames before you commit them. + +3. Name each notebook so the filename matches the slug that page should have on the website. For example, `/learning/courses/my-course/my-file.ipynb` will have the URL https://quantum.cloud.ibm.com/learning/my-course/my-file. + +4. Add the `title` and `description` to the first markdown cell of each notebook using frontmatter format, followed by a top-level heading: + + ``` + --- + title: My title + description: My description + --- + + # My title + ``` + +5. Run `./fix` to lint the notebooks. Ruff might complain about your code: you can either fix it if it's easy enough, or ignore specific rules using the following instructions: + * Create a new code cell at the top of the notebook. + * Add a `remove-cell` tag to the cell. This prevents the cell from displaying on the website. + * Use a comment in that cell to disable specific rules in that notebook. For example, if you wanted to disable rules `E402` and `F811`: + + ```python + # This cell is hidden from users, it disables some lint rules + # ruff: noqa: E402 F811 + ``` + +6. Move any images to `/public/learning/images/courses//`: + * If the images are not `.avif` or `.svg`, you must convert them to `.avif`. Use [ImageMagick](https://imagemagick.org/index.php) for this. You should be able to run `magick path/to/file.png path/to/file.avif` then delete the original file. + * If the images are attachments in the notebook, you'll need to extract them to separate files. Speak to @Frank if you have any questions. + * With the image files in the correct place, update the markdown to point to the new images, leaving off the `public` part of the path. For example, if your file lives in `public/learning/images/courses/my-course/image.avif`, then your markdown should be: + ```markdown + ![alt-text](/learning/images/courses/my-course/image.avif) + ``` + +7. Remove any HTML from the notebooks other than our [supported MDX components](https://github.com/Qiskit/documentation/blob/main/mdx-guide.md). If you need some functionality not supported by the allowed components, let us know and we can help find a solution. + +8. For collapsible content, use `` and `` components. For example: + + ``` + + + Your content here. + + + ``` + + Note that `` titles cannot contain `\pmatrix` equations or images. If your content references either, place it above the `` section. + +9. Replace any YouTube `iframe` tags with a thumbnail image that links to the video using the `` component. See the QCIP course for examples. + +10. Add video embeds to lessons that have accompanying videos. We use IBM Video Streaming with the `` component. The `id` is the IBM Video Streaming ID (not the YouTube ID). In a markdown cell, add the following: + + ``` + In the following video, [presenter name] steps you through the content in this lesson. Alternatively, you can open the [YouTube video](https://youtu.be/YOUR_VIDEO_ID) for this lesson in a separate window. + + + ``` + +11. Add the notebooks to `scripts/config/notebook-testing.toml`. This file tells our testing framework how to test the notebooks. For now, we won't test learning notebooks so you should add their paths to the `groups.exclude` group. + +12. Create an overview page for your course named `index.mdx`. Use the following template to get started: + + ```mdx + --- + title: Overview + description: TODO – SEO description between 50-160 characters + --- + + # Overview + + TODO: Describe your course here + ``` + +13. Add the file owners to `qiskit_bot.yaml`. This file tells us who the points of contact are for each notebook so we can contact them when needed. Add an entry for each notebook and `.mdx` file in your course, listing the relevant GitHub handles. + +14. List your course in `learning/courses/index.mdx` and create a `_toc.json` file for your course. You'll need to manually order the "children" entries in the `_toc.json` to match the intended lesson order. + +15. Run `./check`. This will verify you've done everything correctly so far. It'll also run the spellcheck — follow the instructions from the spellchecker to fix all spelling problems. + +16. With all the checks complete, start up the local preview by opening Rancher Desktop, then running `./start` in your terminal. Find your course and visit each page, checking carefully that everything is displaying correctly. If any pages crash (500 error), it's usually due to HTML in the notebook. If you can't work out why a page is crashing, speak to @Frank and he'll help you debug it. + +17. Run `./fix` and `./check` again to make sure everything still works. If so, you can push your changes and make a pull request! 🎉 From 543cc677a9a8c28057985760c712e4d7344051b1 Mon Sep 17 00:00:00 2001 From: Katie McCormick Date: Wed, 22 Apr 2026 07:57:14 -0700 Subject: [PATCH 2/4] fixed lint error with prettier? --- adding-courses.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/adding-courses.md b/adding-courses.md index 5001039a88b..090dfc7db7c 100644 --- a/adding-courses.md +++ b/adding-courses.md @@ -1,6 +1,6 @@ # Adding courses to Qiskit/documentation -This guide walks through the full process of adding a course to the documentation site. +This guide walks through the full process of adding a course to the documentation site. This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via [NVM](https://github.com/nvm-sh/nvm)), [tox](https://pipx.pypa.io/stable/) (via pipx), and [Rancher Desktop](https://rancherdesktop.io/) installed. @@ -25,9 +25,10 @@ This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via ``` 5. Run `./fix` to lint the notebooks. Ruff might complain about your code: you can either fix it if it's easy enough, or ignore specific rules using the following instructions: - * Create a new code cell at the top of the notebook. - * Add a `remove-cell` tag to the cell. This prevents the cell from displaying on the website. - * Use a comment in that cell to disable specific rules in that notebook. For example, if you wanted to disable rules `E402` and `F811`: + + - Create a new code cell at the top of the notebook. + - Add a `remove-cell` tag to the cell. This prevents the cell from displaying on the website. + - Use a comment in that cell to disable specific rules in that notebook. For example, if you wanted to disable rules `E402` and `F811`: ```python # This cell is hidden from users, it disables some lint rules @@ -35,9 +36,10 @@ This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via ``` 6. Move any images to `/public/learning/images/courses//`: - * If the images are not `.avif` or `.svg`, you must convert them to `.avif`. Use [ImageMagick](https://imagemagick.org/index.php) for this. You should be able to run `magick path/to/file.png path/to/file.avif` then delete the original file. - * If the images are attachments in the notebook, you'll need to extract them to separate files. Speak to @Frank if you have any questions. - * With the image files in the correct place, update the markdown to point to the new images, leaving off the `public` part of the path. For example, if your file lives in `public/learning/images/courses/my-course/image.avif`, then your markdown should be: + + - If the images are not `.avif` or `.svg`, you must convert them to `.avif`. Use [ImageMagick](https://imagemagick.org/index.php) for this. You should be able to run `magick path/to/file.png path/to/file.avif` then delete the original file. + - If the images are attachments in the notebook, you'll need to extract them to separate files. Speak to @Frank if you have any questions. + - With the image files in the correct place, update the markdown to point to the new images, leaving off the `public` part of the path. For example, if your file lives in `public/learning/images/courses/my-course/image.avif`, then your markdown should be: ```markdown ![alt-text](/learning/images/courses/my-course/image.avif) ``` From f79bc1f9e879150b211a0089be76e16d6b39660d Mon Sep 17 00:00:00 2001 From: Katie McCormick <162379175+kcmccormibm@users.noreply.github.com> Date: Mon, 18 May 2026 09:30:06 -0700 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: abbycross --- adding-courses.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/adding-courses.md b/adding-courses.md index 090dfc7db7c..25aa746606a 100644 --- a/adding-courses.md +++ b/adding-courses.md @@ -4,16 +4,16 @@ This guide walks through the full process of adding a course to the documentatio This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via [NVM](https://github.com/nvm-sh/nvm)), [tox](https://pipx.pypa.io/stable/) (via pipx), and [Rancher Desktop](https://rancherdesktop.io/) installed. -1. Make a new folder for the course under `/learning/courses`. The name of this folder will be the slug of the course on the website. For example, `/learning/courses/my-course` will have the URL https://quantum.cloud.ibm.com/learning/my-course. +1. Make a new folder for the course under `/learning/courses`. The name of this folder will be the slug of the course on the website. For example, `/learning/courses/my-course` will have the URL https://quantum.cloud.ibm.com/learning/courses/my-course. 2. Add your notebooks to this folder. > :warning: **Warning:** > Make sure there are no capital letters in your filenames before you commit them. -3. Name each notebook so the filename matches the slug that page should have on the website. For example, `/learning/courses/my-course/my-file.ipynb` will have the URL https://quantum.cloud.ibm.com/learning/my-course/my-file. +3. Name each notebook so the filename matches the slug that page should have on the website. For example, `/learning/courses/my-course/my-file.ipynb` will have the URL https://quantum.cloud.ibm.com/learning/courses/my-course/my-file. -4. Add the `title` and `description` to the first markdown cell of each notebook using frontmatter format, followed by a top-level heading: +4. Add the `title` and `description` to the first markdown cell of each notebook using frontmatter format, followed by a top-level heading (see more info about formatting metadata [here](https://github.com/Qiskit/documentation/blob/main/mdx-guide.md#page-metadata), including min/max number of characters, and what types of characters will break the metadata (e.g., no colons)): ``` --- @@ -37,11 +37,10 @@ This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via 6. Move any images to `/public/learning/images/courses//`: - - If the images are not `.avif` or `.svg`, you must convert them to `.avif`. Use [ImageMagick](https://imagemagick.org/index.php) for this. You should be able to run `magick path/to/file.png path/to/file.avif` then delete the original file. - - If the images are attachments in the notebook, you'll need to extract them to separate files. Speak to @Frank if you have any questions. - - With the image files in the correct place, update the markdown to point to the new images, leaving off the `public` part of the path. For example, if your file lives in `public/learning/images/courses/my-course/image.avif`, then your markdown should be: - ```markdown - ![alt-text](/learning/images/courses/my-course/image.avif) + - If the images are not `.avif` or `.svg`, you must convert them to `.avif` or `.svg`. Use [ImageMagick](https://imagemagick.org/index.php) for this. You should be able to run `magick path/to/file.png path/to/file.svg` then delete the original file. + - If the images are attachments in the notebook, you'll need to extract them to separate files. Speak to @kaelynj if you have any questions. + - With the image files in the correct place, update the markdown to point to the new images, leaving off the `public` part of the path. For example, if your file lives in `public/docs/learning/images/courses/my-course/image.avif`, then your markdown should be: + ``` 7. Remove any HTML from the notebooks other than our [supported MDX components](https://github.com/Qiskit/documentation/blob/main/mdx-guide.md). If you need some functionality not supported by the allowed components, let us know and we can help find a solution. @@ -89,6 +88,6 @@ This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via 15. Run `./check`. This will verify you've done everything correctly so far. It'll also run the spellcheck — follow the instructions from the spellchecker to fix all spelling problems. -16. With all the checks complete, start up the local preview by opening Rancher Desktop, then running `./start` in your terminal. Find your course and visit each page, checking carefully that everything is displaying correctly. If any pages crash (500 error), it's usually due to HTML in the notebook. If you can't work out why a page is crashing, speak to @Frank and he'll help you debug it. +16. With all the checks complete, start up the local preview by opening Rancher Desktop, then running `./start` in your terminal. Find your course and visit each page, checking carefully that everything is displaying correctly. If any pages crash (500 error), it's usually due to HTML in the notebook. If you can't work out why a page is crashing, speak to someone on the content team to help you debug it. 17. Run `./fix` and `./check` again to make sure everything still works. If so, you can push your changes and make a pull request! 🎉 From b17ad06f413d8d57aa6b6f84023a57ec5fa8f013 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Mon, 18 May 2026 13:28:27 -0400 Subject: [PATCH 4/4] npm run fmt (to run Prettier) --- adding-courses.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/adding-courses.md b/adding-courses.md index 25aa746606a..a5eca4fd9c5 100644 --- a/adding-courses.md +++ b/adding-courses.md @@ -4,16 +4,16 @@ This guide walks through the full process of adding a course to the documentatio This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via [NVM](https://github.com/nvm-sh/nvm)), [tox](https://pipx.pypa.io/stable/) (via pipx), and [Rancher Desktop](https://rancherdesktop.io/) installed. -1. Make a new folder for the course under `/learning/courses`. The name of this folder will be the slug of the course on the website. For example, `/learning/courses/my-course` will have the URL https://quantum.cloud.ibm.com/learning/courses/my-course. +1. Make a new folder for the course under `/learning/courses`. The name of this folder will be the slug of the course on the website. For example, `/learning/courses/my-course` will have the URL https://quantum.cloud.ibm.com/learning/courses/my-course. 2. Add your notebooks to this folder. > :warning: **Warning:** > Make sure there are no capital letters in your filenames before you commit them. -3. Name each notebook so the filename matches the slug that page should have on the website. For example, `/learning/courses/my-course/my-file.ipynb` will have the URL https://quantum.cloud.ibm.com/learning/courses/my-course/my-file. +3. Name each notebook so the filename matches the slug that page should have on the website. For example, `/learning/courses/my-course/my-file.ipynb` will have the URL https://quantum.cloud.ibm.com/learning/courses/my-course/my-file. -4. Add the `title` and `description` to the first markdown cell of each notebook using frontmatter format, followed by a top-level heading (see more info about formatting metadata [here](https://github.com/Qiskit/documentation/blob/main/mdx-guide.md#page-metadata), including min/max number of characters, and what types of characters will break the metadata (e.g., no colons)): +4. Add the `title` and `description` to the first markdown cell of each notebook using frontmatter format, followed by a top-level heading (see more info about formatting metadata [here](https://github.com/Qiskit/documentation/blob/main/mdx-guide.md#page-metadata), including min/max number of characters, and what types of characters will break the metadata (e.g., no colons)): ``` --- @@ -37,10 +37,12 @@ This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via 6. Move any images to `/public/learning/images/courses//`: - - If the images are not `.avif` or `.svg`, you must convert them to `.avif` or `.svg`. Use [ImageMagick](https://imagemagick.org/index.php) for this. You should be able to run `magick path/to/file.png path/to/file.svg` then delete the original file. - - If the images are attachments in the notebook, you'll need to extract them to separate files. Speak to @kaelynj if you have any questions. - - With the image files in the correct place, update the markdown to point to the new images, leaving off the `public` part of the path. For example, if your file lives in `public/docs/learning/images/courses/my-course/image.avif`, then your markdown should be: - + - If the images are not `.avif` or `.svg`, you must convert them to `.avif` or `.svg`. Use [ImageMagick](https://imagemagick.org/index.php) for this. You should be able to run `magick path/to/file.png path/to/file.svg` then delete the original file. + - If the images are attachments in the notebook, you'll need to extract them to separate files. Speak to @kaelynj if you have any questions. + - With the image files in the correct place, update the markdown to point to the new images, leaving off the `public` part of the path. For example, if your file lives in `public/docs/learning/images/courses/my-course/image.avif`, then your markdown should be: + + ``` + ``` 7. Remove any HTML from the notebooks other than our [supported MDX components](https://github.com/Qiskit/documentation/blob/main/mdx-guide.md). If you need some functionality not supported by the allowed components, let us know and we can help find a solution. @@ -88,6 +90,6 @@ This guide assumes you have a local clone of Qiskit/documentation, Node 18+ (via 15. Run `./check`. This will verify you've done everything correctly so far. It'll also run the spellcheck — follow the instructions from the spellchecker to fix all spelling problems. -16. With all the checks complete, start up the local preview by opening Rancher Desktop, then running `./start` in your terminal. Find your course and visit each page, checking carefully that everything is displaying correctly. If any pages crash (500 error), it's usually due to HTML in the notebook. If you can't work out why a page is crashing, speak to someone on the content team to help you debug it. +16. With all the checks complete, start up the local preview by opening Rancher Desktop, then running `./start` in your terminal. Find your course and visit each page, checking carefully that everything is displaying correctly. If any pages crash (500 error), it's usually due to HTML in the notebook. If you can't work out why a page is crashing, speak to someone on the content team to help you debug it. 17. Run `./fix` and `./check` again to make sure everything still works. If so, you can push your changes and make a pull request! 🎉