You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+13-11Lines changed: 13 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,7 +48,7 @@ Remember to always activate the right environment before running anything with `
48
48
49
49
50
50
## Repo Organization
51
-
This website uses Quarto to render pages. The main index can be found in `_quarto.yml`, and subpages are organized under the `chapters` section. Each subpage has it's own folder and `.md` (markdown) file. Note that unlike the [Course Notes repo](https://github.com/DS-100/course-notes), the debugging guide rarely runs any code, so we rely on `.md` files rather than `.qmd` to save us the trouble of converting from `.qmd` to `.ipynb` for editing, then back to `.qmd` to render the website. Instead we can make edits directly to the `.md` file.
51
+
This website uses Quarto to render pages. The main index can be found in `_quarto.yml`, and subpages are organized under the `contents` section. Each subpage has it's own folder and `.md` (markdown) file. Note that unlike the [Course Notes repo](https://github.com/DS-100/course-notes), the debugging guide rarely runs any code, so we rely on `.md` files rather than `.qmd` to save us the trouble of converting from `.qmd` to `.ipynb` for editing, then back to `.qmd` to render the website. Instead we can make edits directly to the `.md` file.
52
52
53
53
## Creating a new section
54
54
To start a new document, create an empty folder `topic_name` and create an empty markdown file `topic_name.md`. Start each document like so:
@@ -76,33 +76,33 @@ jupyter:
76
76
77
77
Now, the notebook is ready for writing content. In VSCode, you can activate a live preview of markdown files by clicking the button on the upper right-hand corner.
78
78
79
-
79
+
80
80
81
81
Note that clicking on the quarto `Preview` button does not generate a *live* preview but rather a static one. Hence, we click the button on its right.
82
82
83
83
## Document Formatting
84
-
**Always `git pull` before making any new changes**.
85
84
86
-
A pdf view of how this notebook renders in Quarto can be found [here](https://drive.google.com/file/d/17ga5wvfcmvAzQ1rbnCP4kEf5bckST3--/view?usp=sharing).
85
+
**Always `git pull` before making any new changes**.
87
86
88
87
#### Formatting Images
89
88
90
89
To give you the most control when inserting images, we use html with the following format to center images/figs and control their size:
91
90
92
-
```<center><img src = "IMAGE_NAME" width = "IMAGE_WIDTH_IN_PIXELS" alt="alt text here"></img></a></center>```
91
+
```<center><img src = "IMAGE_NAME" width = "IMAGE_WIDTH_IN_PIXELS" alt="ALT TEXT HERE"></img></a></center>```
93
92
94
93
For example, `<center><img src = "images/updated_basic.png" width = "700" alt="description of image"></img></a></center>`.
95
94
96
-
In some instances, the images may be completely described in the text of the page. In these cases, you may leave the alt text blank i.e. `alt=""`. BUT THE ALT TEXT MUST STILL BE INCLUDED.
97
-
95
+
In some instances, the images may be completely described in the text of the page. In these cases, you may leave the alt text blank i.e. `alt=""`, **but alt text must still be included to meet our legal obligations.**
98
96
99
97
## Generating Output + Rendering Website
100
98
After making edits to the `.md` files, ensure that the right documents are un-commented under `_quarto.yml`'s `chapter` section. Then, make sure you're using the right environment, and run `quarto render` in the main folder to render the entire website.
101
99
102
100
To preview your changes, run `quarto preview`.
103
101
102
+
Not all files in this repository need to be rendered. For example, images used in this README are not used in the website and as such do not need to be included in the rendered website. To ensure these files are not rendered, they are placed in the folder `assets/images/_readme/` which is not rendered because the folder begins with an underscore `_`. Read more about this [here](https://quarto.org/docs/websites/index.html#render-targets).
103
+
104
104
## Pushing to Github
105
-
Once you're satisfied and *thoroughly tested* your changes, you can push your edits onto Github. There are two ways to do this:
105
+
Once you're satisfied and have *thoroughly tested* your changes, you can push your edits onto Github. There are two ways to do this:
106
106
107
107
1.**Command Line**. Navigate to the main `debugging-guide` folder if you haven't already and make sure you're in the right environment.
108
108
@@ -114,11 +114,13 @@ git push # push your changes to github
114
114
115
115
2.**Github Desktop** ([download](https://desktop.github.com/)). This is the GUI version of the command line.
116
116
117
-
* Choose the files you want to commit on the left hand menu. By default, github will select all changes/new files. 
118
-
* Write an informative comment on the bottom left hand corner and click "commit to main" once finished 
117
+
* Choose the files you want to commit on the left hand menu. By default, github will select all changes/new files. 
118
+
* Write an informative comment on the bottom left hand corner and click "commit to main" once finished 
119
119
* Push your changes using the button on the top right.
120
120
121
-
Once your changes are pushed, you can see the progress of your build in the ["Actions" tab](https://github.com/DS-100/debugging-guide/actions); green means the website built successfully, yellow/orange indicates that it's still building, and red means there was an error and the website was unable to build. The website should take less than 5 minutes to build, and you will see the changes reflected in the [website](https://ds100.org/debugging-guide/).
121
+
Once your changes are pushed, you can see the progress of your build in the ["Actions" tab](https://github.com/DS-100/debugging-guide/actions). The Actions tab monitors all workflows. Currently there are two workflows: "pages-build-deployment" which builds and deploys the website, and "Accessibility Checks." If both checks complete successfully, you will see a green checkmark next to each workflow's most recent run on the Actions page as well as a green checkmark on the main repo page for the associated commit. Yellow/orange indicates that checks are still running, meaning that the website may not be deployed yet. Red means that at least one check was unable to complete successfully. You should always investigate if you see a red mark; It's possible that the website deployed successfully but the accessibility checks failed, or vice versa.
122
+
123
+
The website should take less than 5 minutes to deploy, and you will see the changes reflected in the [website](https://ds100.org/debugging-guide/).
0 commit comments