Skip to content

add adding courses guide#5018

Open
kcmccormibm wants to merge 2 commits into
mainfrom
km/adding-courses-guide
Open

add adding courses guide#5018
kcmccormibm wants to merge 2 commits into
mainfrom
km/adding-courses-guide

Conversation

@kcmccormibm
Copy link
Copy Markdown
Collaborator

fixes #4941

@kaelynj let me know if this is okay! I added a new file and linked it in the README

@qiskit-bot
Copy link
Copy Markdown
Contributor

Thanks for contributing to Qiskit documentation!

Before your PR can be merged, it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient. Thanks! 🙌

Copy link
Copy Markdown
Collaborator

@kaelynj kaelynj left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great thank you @kcmccormibm! 🚀

Comment thread adding-courses.md

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.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread adding-courses.md
> :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.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread adding-courses.md

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:
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)):

Comment thread adding-courses.md

6. Move any images to `/public/learning/images/courses/<your-course-name>/`:

- 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.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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 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.

I think svg is actually preferred, though I would need to confirm

Comment thread adding-courses.md
6. Move any images to `/public/learning/images/courses/<your-course-name>/`:

- 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.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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.
- 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.

Comment thread adding-courses.md
Comment on lines +42 to +44
- 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)
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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)
- 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:
```markdown
![alt-text](/docs/learning/images/courses/my-course/image.avif)

Comment thread adding-courses.md

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.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Copy Markdown
Collaborator

@abbycross abbycross left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks so much Katie! I made a few clarifications and fixes.

@github-project-automation github-project-automation Bot moved this to In Review in Docs Planning May 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Review

Development

Successfully merging this pull request may close these issues.

Add new course instructions to README

4 participants