feat: add how to preview documentation modification

docs/contributing/documentation-guidelines/index.md

@@ -1,5 +1,7 @@
 # Documentation guidelines
 
+## Workflow
+
 Contributions to Autoware's documentation are welcome, and the same principles [described in the contribution guidelines](../index.md#pull-requests) should be followed. Small, limited changes can be made by forking this repository and submitting a pull request, but larger changes should be discussed with the community and Autoware maintainers via GitHub Discussion first.
 
 Examples of small changes include:
@@ -13,9 +15,46 @@ Examples of larger changes include:
 - Adding new pages with a large amount of detail, such as a tutorial
 - Re-organization of the existing documentation structure
 
-In terms of style, you should refer to the [Google developer documentation style guide](https://developers.google.com/style) as much as possible. Reading the [Highlights page](https://developers.google.com/style/highlights) of that guide is recommended, but if not then the key points below should be noted.
+## Style guide
+
+You should refer to the [Google developer documentation style guide](https://developers.google.com/style) as much as possible. Reading the [Highlights page](https://developers.google.com/style/highlights) of that guide is recommended, but if not then the key points below should be noted.
 
 - [Use standard American English spelling](https://developers.google.com/style/spelling) and punctuation.
 - [Use sentence case](https://developers.google.com/style/capitalization) for document titles and section headings.
 - [Use descriptive link text](https://developers.google.com/style/link-text).
 - [Write short sentences](https://developers.google.com/style/translation#write-short,-clear,-and-precise-sentences) that are easy to understand and translate.
+
+## Tips
+
+### How to preview your modification
+
+There are two ways to preview your modification on a documentation website.
+
+#### 1. Using GitHub Actions workflow
+
+Follow the steps below.
+
+1. Create a pull request to the repository.
+2. Add the `documentation` label from the sidebar (See below figure).
+3. Wait for a couple of minutes, and the `github-actions` bot will notify the URL for the pull request's preview.
+
+![documenatation_label](images/documentation_label_for_pull_request.png){ width="800" }
+
+#### 2. Running an MkDocs server in your local environment
+
+Instead of creating a PR, you can use the `mkdocs` command to build Autoware's documentation websites on your local computer.
+Assuming that you are using Ubuntu OS, run the following to install the required libraries.
+
+```bash
+python3 -m pip install -U $(curl -fsSL \
+  https://raw.githubusercontent.com/autowarefoundation/autoware-github-actions/main/deploy-docs/mkdocs-requirements.txt)
+```
+
+Then, run `mkdocs serve` on your documentation directory.
+
+```bash
+cd /PATH/TO/YOUR-autoware-documentation
+mkdocs serve
+```
+
+It will launch the MkDocs server. Access [http://127.0.0.1:8000/](http://127.0.0.1:8000/) to see the preview of the website.

mkdocs.yml

@@ -0,0 +1,85 @@
+site_name: Autoware Documentation
+site_url: https://autowarefoundation.github.io/autoware-documentation
+repo_url: https://github.com/autowarefoundation/autoware
+edit_uri: https://github.com/autowarefoundation/autoware-documentation/edit/main/docs/
+docs_dir: docs
+copyright: Copyright © 2022 The Autoware Foundation
+
+theme:
+  name: material
+  features:
+    - navigation.expand
+    - navigation.indexes
+    - navigation.instant
+    - navigation.sections
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+  favicon: assets/images/autoware-foundation.png
+  icon:
+    logo: fontawesome/solid/car
+    repo: fontawesome/brands/github
+  language: en
+  palette:
+    - scheme: default
+      primary: white
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - scheme: slate
+      primary: grey
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+
+extra:
+  font:
+    text: Roboto
+    code: Roboto Mono
+  version:
+    provider: mike
+
+extra_css:
+  - assets/css/extra.css
+  - https://use.fontawesome.com/releases/v5.15.4/css/all.css
+
+extra_javascript:
+  - https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML
+
+plugins:
+  - awesome-pages
+  - exclude:
+      regex:
+        - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?jpg).*$
+        - ^(.*/)?[^.]*$
+  - macros
+  - same-dir
+  - search
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - codehilite:
+      guess_lang: false
+  - fontawesome_markdown
+  - footnotes
+  - mdx_math
+  - mdx_truly_sane_lists:
+      nested_indent: 2
+  - plantuml_markdown:
+      server: http://www.plantuml.com/plantuml
+      format: svg
+  - pymdownx.arithmatex
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.snippets:
+      auto_append:
+        - includes/abbreviations.md
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - toc:
+      permalink: "#"