add adding courses guide#5018
Conversation
|
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! 🙌 |
kaelynj
left a comment
There was a problem hiding this comment.
This looks great thank you @kcmccormibm! 🚀
|
|
||
| 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. |
There was a problem hiding this comment.
| 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. |
| > :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. |
There was a problem hiding this comment.
| 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. |
|
|
||
| 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: |
There was a problem hiding this comment.
| 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)): |
|
|
||
| 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. |
There was a problem hiding this comment.
| - 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
| 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. |
There was a problem hiding this comment.
| - 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. |
| - 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 | ||
|  |
There was a problem hiding this comment.
| - 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 | |
|  | |
| - 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 | |
|  |
|
|
||
| 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. |
There was a problem hiding this comment.
| 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. |
abbycross
left a comment
There was a problem hiding this comment.
Thanks so much Katie! I made a few clarifications and fixes.
fixes #4941
@kaelynj let me know if this is okay! I added a new file and linked it in the README