Improve documentation for writing documentation

docs/programming/Laptop-Rules.md

@@ -11,7 +11,7 @@ layout: default
 Common sense. That's about it.
 
 - Don't steal someone else's laptop. (They'll have masking tape with their name on theirs if they've claimed one.)
-- Don't install programs that aren't needed. They take up space on the laptops and will have to be uninstalled later, taking up precious team time. If you really need it, use the web version (Spotify, Discord, etc.)
-- These are not "your" laptops. They are team laptops. Some personalization is okay, but don't overhaul the device.
-- When installing programs, check with a coach or at least a programming lead to make sure it's okay.
+- **Don't install programs that aren't needed**. They take up space on the laptops and will have to be uninstalled later, taking up precious team time. If you really need it, use the web version (Spotify, Discord, etc). If you aren't sure if a program is needed, you can always ask a lead!
+- These are not "your" laptops. They are team laptops. Some personalization is okay, but don't overhaul the device. 
+- When installing programs, **check with a coach or at least a programming lead to make sure it's okay**.
 - Don't mess with the laptop. No pulling out keys, no stealing the plastic SD card slot fillers, no scratching at the plastic coating to make it look weird. Don't commit stupid.

docs/writing_documentation/How-to-create-pages.md

@@ -1,17 +1,135 @@
 # How to create pages
 
 1. Go to the [team documentation repository](https://github.com/Team2530/Documentation).
-2. Navigate to the correct folder for 
-
-1. Go to https://github.com/Team2530/Documentation/
 2. Press the '.' key on your keyboard. This will open github.dev.
 3. Add a new file called pagename.md
 4. Add content to the file
     - The file is a markdown file. You can read about markdown here: https://help.github.com/articles/basic-writing-and-formatting-syntax
-    - You should include a title at the start
+    - You should include a title at the start, like so:
 ```md
 # My Title
+Some content.
+![an image](assets/logo.svg)
 ```
     - You should split the document into multiple sections
-5. Add the new page to the [index](./index). NOTE: Do **NOT** add the `.md` file extension to the link.
-6. Commit and push your code to github
+6. Commit and push your code to github. The documentation repository is generally an exception to the branching rules, so feel free to push to main instead of making a pull request.
+
+### Using Admonitions
+This documentation site supports [the admonitions plugin](https://squidfunk.github.io/mkdocs-material/reference/admonitions/). This allows for easy creation of alert boxes.
+
+For example, this code:
+```md
+!!! note
+    Hello, world
+```
+
+Creates this:
+!!! note
+    Hello, world
+
+#### Supported types
+* note
+* abstract
+* info
+* tip
+* success
+* question
+* warning
+* failure
+* danger
+* bug
+* example
+* quote
+
+#### Changing the admonition title
+You can change the admonition title by adding a string literal after the type of admonition.
+
+=== "Markdown"
+    ```md title="Adding a title"
+    !!! note "Hello, world"
+        Hello, world
+    ```
+=== "Result"
+    !!! note "Hello, world"
+        Hello, world
+
+#### Collapsible
+Another notable feature of admonitions is the support for collapsable alerts.
+This can be achieved by replacing the exclamation points with question marks.
+
+=== "Markdown"
+    ```md
+    ??? note
+        Hello, world
+    ```
+=== "Result"
+    ??? note
+        Hello, world
+
+### Adding code
+Adding blocks of code to documentation is very simple. All you need to do is add something like this in the markdown file:
+````md
+```py
+print('hello world')
+```
+````
+
+#### Adding a title to the code
+Sometimes you may want to add a file name or some other title to a block of code. This is possible using the title argument:
+
+=== "Markdown"
+    ````md
+    ```py title="Hello, world"
+    print("hello world")
+    print("5 10 15 20")
+    print("inconceivable")
+    ```
+    ````
+=== "Result"
+    ```py title="Hello, world"
+    print("hello world")
+    print("5 10 15 20")
+    print("inconceivable")
+    ```
+
+#### Highlighting specific lines of code
+You can highlight specific lines using `hl_lines=[...]`
+
+=== "Markdown"
+    ````md
+    ```py hl_lines="2"
+    print("hello world")
+    print("5 10 15 20")
+    print("inconceivable")
+    ```
+    ````
+
+=== "Result"
+    ```py hl_lines="2"
+    print("hello world")
+    print("5 10 15 20")
+    print("inconceivable")
+    ```
+
+### Adding images
+You can add images to documentation with the following syntax:  
+```md
+![image caption](path/to/image)
+```
+
+All images should be stored in the folder `docs/assets` for organization purposes. Also, it is better if you download any images you use and put them in this repository than link to somewhere else on the internet.
+
+The following code displays the image below:
+```md
+![image caption](../assets/random-image.jpg)
+```
+![image caption](../assets/random-image.jpg)
+
+### Adding diagrams
+!!! warning "Tricky stuff ahead"
+    Adding diagrams can be difficult, and only experienced markdown users should attempt to do it. If you don't know a lot about markdown, it is way easier to just insert an image instead.
+This documentation site supports rendering of MermaidJS diagrams. You can read more about it and see some examples here: https://squidfunk.github.io/mkdocs-material/reference/diagrams/.
+
+### Math
+It is possible to insert math that is rendered properly on the page, but it may not be properly configured for this site.  
+For more information, see [the official material for mkdocs page on the topic](https://squidfunk.github.io/mkdocs-material/reference/math/).