Skip to content

Commit

Permalink
Update building_docs.md for spelling and legibility
Browse files Browse the repository at this point in the history
  • Loading branch information
@Danura30082
Danura30082 authored Nov 27, 2024
1 parent f30b1a0 commit 6e6692a
Showing 1 changed file with 41 additions and 46 deletions.
87 changes: 41 additions & 46 deletions docs/building_docs.md
View file
Original file line number Diff line number Diff line change
@@ -1,53 +1,52 @@
# How to use Markdown and MkDocs

# How to use markdown and Mkdocs

This documentaion is build using markdown and Mkdocs. This page is a guide to get you started to contribute.
This documentation is built using Markdown and MkDocs. This page is a guide to get you started contributing.

## What is Markdown

> Markdown is a lightweight markup language used to format text in a simple and readable way. It uses plain-text syntax to define elements like headings, lists, links, and emphasis (e.g., **bold**, *italic*). Markdown is commonly used in documentation, blogging platforms, and version control systems like GitHub because it is easy to write and converts seamlessly into HTML for web display. -ChatGPT
Markdown files are often recongisable by their `.md` and rarley `.markdown` file extentions.
Markdown files are often recognizable by their `.md` and rarely `.markdown` file extensions.

## Basic syntax
## Basic Syntax

### Bold and italics
### Bold and Italics

To make bold text, surround your text with asterisks:
To make bold text, surround your text with double asterisks:
<table>
<tr>
<td>**This text will be bolded**</td>
<td><b>This text will be bolded</b></td>
</tr>
</table>

For italics we use a single asterisk:
For italics, use a single asterisk:
<table>
<tr>
<td>*This text will be put in italics*</td>
<td><i>This text will be put in italics</i></td>
<td>*This text will be italicized*</td>
<td><i>This text will be italicized</i></td>
</tr>
</table>

These may be combined:
These can be combined:
<table>
<tr>
<td>***This text will be bold and italic***</td>
<td><b><i>This text will be bold and italic</i></b></td>
</tr>
</table>

### Heading
### Headings

Heading are denoted unding a ## at the begin of a line. The number of ## determins the depth of the header
Headings are denoted using `#` at the beginning of a line. The number of `#` determines the depth of the header:

| Input | Render |
|------------------|------------------ |
| ## Heading 1 | <h1> Heading 1 </h1> |
| ### Heading 2 | <h2> Heading 2 </h2> |
| #### Heading 3 | <h3> Heading 3 </h3> |
| ##### Heading 4 | <h4> Heading 4 </h4> |
| ###### Heading 5 | <h5> Heading 5 </h5> |
| # Heading 1 | <h1> Heading 1 </h1> |
| ## Heading 2 | <h2> Heading 2 </h2> |
| ### Heading 3 | <h3> Heading 3 </h3> |
| #### Heading 4 | <h4> Heading 4 </h4> |
| ##### Heading 5 | <h5> Heading 5 </h5> |

!!! warning
A space is required for a heading to work.
Expand All @@ -57,22 +56,22 @@ Heading are denoted unding a ## at the begin of a line. The number of ## determi

### Links

To add links use the folowing syntax:
To add links, use the following syntax:

\[The text that wil be displayed](The link to follow)
\[The text that will be displayed](The link to follow)

\[A link to exemple.org](https://example.org/)
\[A link to example.org](https://example.org/)

[A link to exemple.org](https://example.org/)
[A link to example.org](https://example.org/)

!!! Note
These can be used for internal links as well. For exemple we can link this section with \[Links](#Links) or \[Links](/building_docs/#Links): [Links](#links).
These can be used for internal links as well. For example, we can link this section with \[Links](#Links) or \[Links](/building_docs/#Links): [Links](#links).

The second method can be generalized to reach any page or header on the website.

### Images

The syntax to add images is almost the same as links. Alt text is the text used accesibility readers. it should therefore be descriptive rather than a title.
The syntax to add images is almost the same as links. Alt text is the text used by accessibility readers. It should therefore be descriptive rather than a title.

\!\[Alt text](path/to/image.png)

Expand All @@ -81,7 +80,7 @@ The syntax to add images is almost the same as links. Alt text is the text used
![A square version of the autotech logo. It is used as a favicon for the site](img/favicon.png)

!!! Note
See [Images in HTML](#images-in-html) for more fine grain control of images
See [Images in HTML](#images-in-html) for more fine-grain control of images.

### Code Blocks

Expand All @@ -100,12 +99,11 @@ def hello_world():
print("Hello, world!")
```

You can also create inline code by wrapping text in single backticks (\`). For example, \`print("Hello, world!")\` renderes as `print("Hello, world!")`.

You can also create inline code by wrapping text in single backticks (\`). For example, \`print("Hello, world!")\` renders as `print("Hello, world!")`.

## Advanced syntax
## Advanced Syntax

Markdown strenght is in simplicity of writing but that sometimes comes back to bite us when trying to do someting a little more complicated. Luckly most Markdown renders rendre it as HTML and accept some HTML in markdown files. THis is the case of Mkdocs and Github. **HTML should only be used as necessary.**
Markdown's strength is in the simplicity of writing, but that sometimes comes back to bite us when trying to do something a little more complicated. Luckily, most Markdown renderers accept some HTML in Markdown files. This is the case with MkDocs and GitHub. **HTML should only be used as necessary.**

### Comments

Expand All @@ -115,9 +113,9 @@ In Markdown, there is no built-in syntax for comments. However, you can use HTML
<!-- This is a comment and will not be rendered in the final output -->
```

### Images in Html
### Images in HTML

Images are impossible to scale or rendre next to text. Using the HTML `<img>` tag it possible to customize your images behaviour. Here is an example of an image that is scaled and displayed to the right. Keep in mind that images **can't** be rendered above the postion of the `<img>` tag:
Images are impossible to scale or render next to text. Using the HTML `<img>` tag, it is possible to customize your image's behavior. Here is an example of an image that is scaled and displayed to the right. Keep in mind that images **can't** be rendered above the position of the `<img>` tag:

```
<img src="../img/favicon.png" alt="A square version of the autotech logo. It is used as a favicon for the site" title="A UST-10lx Lidar" width="200" align="right"/>
Expand All @@ -126,14 +124,13 @@ Images are impossible to scale or rendre next to text. Using the HTML `<img>` ta
<img src="../img/favicon.png" alt="A square version of the autotech logo. It is used as a favicon for the site" title="A UST-10lx Lidar" width="200" align="right"/>

!!! warning
due diffence in how the HTML and markdown are compiled, there are diffrent paths when adding images in html and markdown

Due to differences in how the HTML and Markdown are compiled, there are different paths when adding images in HTML and Markdown.

<div style="clear: both;"></div> <!-- ensure no overlap with next element -->

### Admonitions

Admonitions are a way to highlight important information in your documentation. MkDocs supports several types of admonitions, such as notes, warnings/caution, danger and tips/hint. Here is an example of how to use them:
Admonitions are a way to highlight important information in your documentation. MkDocs supports several types of admonitions, such as notes, warnings/caution, danger, and tips/hint. Here is an example of how to use them:

```
!!! note
Expand All @@ -149,33 +146,31 @@ Admonitions are a way to highlight important information in your documentation.
!!! warning
This is a warning admonition.

## Using MkDocs

## Using Mkdocs

For full documentation visit [mkdocs.org](https://www.mkdocs.org).
For full documentation, visit [mkdocs.org](https://www.mkdocs.org).

### Commands

* `mkdocs serve` - Start the live-reloading docs server. It should now be accesible at [127.0.0.1:8000](http://127.0.0.1:8000/) on ***your machine***
* `mkdocs gh-deploy` - Build the documentation site on the gh-pages branch of you repository.
* `mkdocs serve` - Start the live-reloading docs server. It should now be accessible at [127.0.0.1:8000](http://127.0.0.1:8000/) on ***your machine***.
* `mkdocs gh-deploy` - Build the documentation site on the gh-pages branch of your repository.

!!! Note
On the [Club-INTech/CoVAPSy](https://github.com/Club-INTech/CoVAPSy) repository `mkdocs gh-deploy` is automaticly called upon push to main branch. It can still be manually called when on another branch but [gh-pages](https://github.com/Club-INTech/CoVAPSy/tree/gh-pages) will be overwritten by any push on main
On the [Club-INTech/CoVAPSy](https://github.com/Club-INTech/CoVAPSy) repository, `mkdocs gh-deploy` is automatically called upon push to the main branch. It can still be manually called when on another branch, but [gh-pages](https://github.com/Club-INTech/CoVAPSy/tree/gh-pages) will be overwritten by any push on main.

### Project layout
### Project Layout

mkdocs.yml ## The configuration file.
docs/
index.md ## The documentation homepage.
... ## Other markdown pages, images and other files.
... ## Other markdown pages, images, and other files.
img/
favicon.png ## The icon that appears on the browser tab.
... other images

### Using Github pages
### Using GitHub Pages

Navigate to the repository then to settings/pages. Using the drop down menus select "Deploy from branch" for source and "gh-pages" and "/root" for branch.
Navigate to the repository, then to settings/pages. Using the drop-down menus, select "Deploy from branch" for source and "gh-pages" and "/root" for branch.

!!! Note
You may have to run `mkdocs gh-deploy` for the gh-pages branch to show. See [Commands](#commands)

You may have to run `mkdocs gh-deploy` for the gh-pages branch to show. See [Commands](#commands).

0 comments on commit 6e6692a

Please sign in to comment.