Merge pull request #1 from TGITS/feat/wip_for_article

Building example site for article on Medium

README.md

@@ -1,2 +1,37 @@
 # fun-with-mkdocs
+
 Example project that demonstrate the use of mkdocs and material for mkdocs
+
+## Using with Python
+
+If you already have Python installed on yoyr system or you prefer use mkdocs withuout using Docker, the recommended steps are the following :
+
+* Create a virtual environment with `venv` (it is bundled with Python) before installing **MkDocs** :
+  * In a shell, at the root of the directory in which you want to install mkdocs, type : `python -m venv venv --prompt="mkdocs"`
+  * A `venv` directory should be created : add this directory to the `.gitignore`
+* Activate the virtual environnement : `venv\Scripts\activate`
+* Install **MkDocs (with Material)** with `pip`
+  * `pip install mkdocs-material`
+  * Now **MkDocs** is installed in your virtual environment
+* When you have finished your work session in the shell, remember to deactivate your virtual environment : `venv\Scripts\deactivate`
+
+When the installation is done, the following commands are available :
+
+* Initialization : `mkdocs new <documentation-project-name>`
+  * Only to initialize the MkDocs project, you should execute this command only once.
+* Previsualization : `mkdocs serve` or `mkdocs serve --dirtyreload` if you only want to update the current page (incomplete but faster build of the site).
+* Building of the site : `mkdocs build`
+  * The HTML files of the site are generated in the directory `site/fun-with-mkdocs`
+  * They can be open directly with your browser.
+
+Remember to activate your virtual environment before running the **MkDocs** commands : `venv\Scripts\activate`
+And remember to activate it when you have finished your work session (if you forgot it is the end of the world, particularly if you close your shell) : `venv\Scripts\deactivate`.
+
+## Using with Docker
+
+[MkDocs](https://www.mkdocs.org/) can be used without installation with [Docker](https://www.docker.com/).
+
+* To initialize the site, in the directory in which you want to create if : `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .`
+* Previzualisation on `localhost:8000` : `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material`
+* Building of the site : `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build`
+  * The HTML files of the site are generated in the directory `site/fun-with-mkdocs`

docs/configuration_example.md

@@ -0,0 +1,152 @@
+---
+title: Page configuration and extensions example usage
+description: Some page configuration and extensions usage examples
+status: new
+---
+
+## Goals of this page
+
+This page aims to demonstrate some examples of a page configuration and examples usage of some extensions.
+
+## Emoji :smile:
+
+* :grinning_face:
+* :cold_face:
+* :nerd_face:
+* :rolling_on_the_floor_laughing:
+* :broken_heart:
+* :alien:
+
+Some of the codes from this [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) works.
+
+## Admonition examples
+
+!!! note
+
+    note admonition example - not collapsible
+
+??? info
+
+    info admonition example - collapsible, not expanded by default
+
+???+ tip
+
+    tip admonition example - collapsible, expanded by default
+
+!!! warning
+
+    warning admonition example - not collapsible
+
+???+ example
+
+    example admonition example - collapsible, expanded by default
+
+## Code blocks examples
+
+```java title="frequencies-map-with-for.jsh"
+/**
+ * Run with JBang : jbang frequencies-map-with-for.jsh (1)
+ * <p>
+ * or open in JShell : /open frequencies-map-with-for.jsh
+ */
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+List<String> daysOfWeek = List.of("Friday", "Thursday", "Thursday", "Saturday", "Thursday", "Thursday", "Monday", "Saturday", "Friday", "Saturday");
+Map<String, Integer> frequencies = new HashMap<>();
+int previousCount;
+for (String day : daysOfWeek) {
+    previousCount = frequencies.getOrDefault(day, 0);
+    frequencies.put(day, previousCount + 1);
+}
+
+frequencies.entrySet().iterator().forEachRemaining(System.out::println);
+```
+
+1. :man_raising_hand: Code annotation example
+
+## Tables examples
+
+### Sortable table with no alignement specified for columns
+
+| AtomicNumber | Symbol | Name      | AtomicMass  |
+| ------------ | ------ | --------- | ----------- |
+| 1            | H      | Hydrogen  | 1.0080      |
+| 2            | He     | Helium    | 4.00260     |
+| 3            | Li     | Lithium   | 7.0         |
+| 4            | Be     | Beryllium | 9.012183    |
+
+### Sortable table with columns aligned to left
+
+| AtomicNumber | Symbol | Name      | AtomicMass  |
+| :----------- | :----- | :-------- | :---------- |
+| 1            | H      | Hydrogen  | 1.0080      |
+| 2            | He     | Helium    | 4.00260     |
+| 3            | Li     | Lithium   | 7.0         |
+| 4            | Be     | Beryllium | 9.012183    |
+
+### Sortable table with columns centered
+
+| AtomicNumber | Symbol | Name      | AtomicMass  |
+| :----------: | :----: | :-------: | :---------: |
+| 1            | H      | Hydrogen  | 1.0080      |
+| 2            | He     | Helium    | 4.00260     |
+| 3            | Li     | Lithium   | 7.0         |
+| 4            | Be     | Beryllium | 9.012183    |
+
+### Sortable table with columns aligned to right
+
+| AtomicNumber | Symbol | Name      | AtomicMass  |
+| -----------: | -----: | --------: | ----------: |
+| 1            | H      | Hydrogen  | 1.0080      |
+| 2            | He     | Helium    | 4.00260     |
+| 3            | Li     | Lithium   | 7.0         |
+| 4            | Be     | Beryllium | 9.012183    |
+
+## Diagrams with Mermaid examples
+
+Hereafter an example with a class and a sequence diagram (inspired by the [Visitor Pattern](https://refactoring.guru/design-patterns/visitor)) but any diagram supported by [mermaid](https://mermaid.js.org/) is possible.
+
+```mermaid
+classDiagram
+    class Visitor{
+        +visit(ConcreteElementA element)
+        +visit(ConcreteElementB element)
+    }
+
+    <<interface>> Visitor
+
+    class ConcreteVisitorA {
+        +visit(ConcreteElementA element)
+        +visit(ConcreteElementB element)
+    }
+
+    Visitor <|.. ConcreteVisitorA
+
+    class Element{
+        +accept(Visitor visitor)
+    }
+
+    <<interface>> Element
+
+    class ConcreteElementA{
+        +accept(Visitor visitor)
+    }
+
+    class ConcreteElementB{
+        +accept(Visitor visitor)
+    }
+
+    Element <.. ConcreteElementA
+    Element <.. ConcreteElementB
+
+```
+
+```mermaid
+sequenceDiagram
+  client->>concreteElementA: accept(visitor)
+  concreteElementA->>visitor: visit(concreteElementA)
+  client->>concreteElementB: accept(visitor)
+  concreteElementB->>visitor: visit(concreteElementA)
+```

docs/index.md

@@ -0,0 +1,19 @@
+# Fun with MkDocs
+
+The full documentation is available at [mkdocs.org](https://www.mkdocs.org).
+
+## Quick Cheatsheet
+
+### Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+### Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

docs/installing-and-running-mkdocs.md

@@ -0,0 +1,62 @@
+# Installing and running MkDocs
+
+In the following example, I will use MkDocs with the theme Material.
+
+The two main ways to install and run MkDocs that I will present are with Python and with Docker.
+
+## Installing MkDocs with Python
+
+MkDocs is a Python application. So the most obvious way to use it, is to install it via Python. 
+It's a good option if you already have Python installed. 
+If it is not the case and you do not want to install Python on your system only for MkDocs, we will see later another option using a container.
+
+To install MkDocs (or in our case MkDocs with the material theme included) we will use pip. I also use a virtual environment it is recommended but not mandatory.
+
+The following procedure supposes that you have Python installed and describes the installation with a virtual environment (venv is used here because it comes bundle with Python) for the ones who are not familiar with it. However you can install MkDocs without a virtual environment : the procedure will be the same (except for the part related to the virtual environment obviously) and MkDocs will be installed globally to your system.
+Create the directory in which you want to put your documentation managed by MkDocs, open a shell and go to this directory. In my example the directory is named "fun-with-mkdocs".
+
+Open a shell, and go to the root of this directory.
+Then type the following to create a virtual environment :
+
+```text
+python -m venv venv --prompt="mkdocs"
+```
+
+![Screenshot](./assets/images/fun-with-mkdocs-001.png)
+
+A directory venv should have been created. If you use git and have a gitignore file you should add to it the directory venv.
+Activate the virtual environment by typing :
+
+```text
+venv\Scripts\activate
+```
+
+![Screenshot](./assets/images/fun-with-mkdocs-002.png)
+
+Now we will install MkDocs and the material theme with pip by typing
+
+```text
+pip install mkdocs-material
+```
+
+Several components are installed, it takes some times and you should have something similar to the (partial) trace thereafter.
+
+![Screenshot](./assets/images/fun-with-mkdocs-003.png)
+
+![Screenshot](./assets/images/fun-with-mkdocs-004.png)
+
+Congratulation, MkDocs should be installed. To confirm it, type `mkdocs -h`
+
+The help of MkDocs should be displayed.
+
+![Screenshot](./assets/images/fun-with-mkdocs-005.png)
+
+## Using a container
+
+To be able to use this option, you must have Docker or Podman (on Windows I personally use Podman Desktop rather than Docker Desktop) installed and running on your system.
+
+You can first pull the official Docker image (hereafter the official one for MkDocs with Material) by typing `docker pull squidfunk/mkdocs-material`.
+
+![Screenshot](./assets/images/fun-with-mkdocs-006.png)
+
+If you successfully pull the image you should be able to run and use MkDocs. But more about that in the following section : if you are using a container to work with MkDocs, this is pretty much it for the installation part.

docs/javascripts/tablesort.js

@@ -0,0 +1,6 @@
+document$.subscribe(function() {
+    var tables = document.querySelectorAll("article table:not([class])")
+    tables.forEach(function(table) {
+      new Tablesort(table)
+    })
+  })

docs/mkdocs-briefly.md

@@ -0,0 +1,5 @@
+# MkDocs briefly
+
+Before entering in the core of the matter, a brief presentation of MkDocs : it is a static site generator in Python with a focus towards project documentation. The documentation source files themselves are written in Markdown and the configuration is written in a single YAML file.
+It is possible to customize the theme used by MkDocs and there is already a very good Material theme available which will be used throughout this post.
+There are also several plugins that can greatly help with your documentation. We will see some of them in this post.

mkdocs.yml

@@ -0,0 +1,57 @@
+site_name: Fun with Mkdocs !
+
+theme:
+  name: material
+  language: en # language of the site
+  features:
+    - navigation.tabs # To have tabs instead of links
+    - navigation.tabs.sticky # So have the tabs always present at the top of the page, event when you scroll down
+    - navigation.tracking # the url evolves with the scrolling
+    - toc.integrate # to have a toc on the left
+    - navigation.top # to have a shorcut to go back on top of the page when we scroll down
+    - content.code.copy # to have copy button with code blocks
+    - content.code.annotate # to be able to annotate in code blocks
+
+nav:
+  - 'Home': 'index.md'
+  - 'Introduction': 'mkdocs-briefly.md'
+  - 'Installation': 'installing-and-running-mkdocs.md'
+  - 'Configuration example': 'configuration_example.md'
+
+plugins:
+  - search
+  - offline
+
+markdown_extensions:
+  # Required for multiple other extensions
+  - attr_list # required for annotations, icons and emoji
+  - md_in_html # required for icons and emoji
+  - pymdownx.superfences # required for admonitions and code blocks
+  # For admonitions
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences: # Required for admonitions, diagrams and code blocks
+      # For using mermaid for inline diagrams
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  # For using a large database of icons and emojis
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  # For code blocks
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  # For tables
+  - tables
+
+extra_javascript:
+  # For sortable tables
+  # You need to have some javascript code in docs/javascripts/tablesort.js
+  - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
+  - javascripts/tablesort.js