Merge pull request #15 from PythonBiellaGroup/develop

add mdkocs tutorial content

Author: airaghidavide

README.md

@@ -68,7 +68,7 @@ In the PBG website you can find:
 - [x] Quick feedback
 - [x] Cookies request form
 - [x] Migrate contents from old site
-- [ ] Template folder for contents
+- [x] Template folder for contents
 - [ ] New home page
 - [ ] New 404 page
 - [ ] New CSS to improve design

docs/blog/index.md

@@ -1,5 +1,8 @@
 ---
 exclude_from_blog: true
+hide:
+  - toc
+  - feedback
 ---
 
 # Blog

docs/blog/posts/new_brand_identity.en.md

@@ -6,6 +6,9 @@ timetoread: true
 tags:
  - brand identity
  - design
+hide:
+  - toc
+  - feedback
 ---
 
 # Our new brand identity

docs/blog/posts/new_brand_identity.md

@@ -6,6 +6,9 @@ timetoread: true
 tags:
  - brand identity
  - design
+hide:
+  - toc
+  - feedback
 ---
 
 # La nostra nuova brand identity

docs/learning/mkdocs_tutorial/extra_functions.en.md

@@ -138,8 +138,74 @@ extra_css:
 
 ## Writing scientific equations
 
+With MkDocs Material, it's possible to include complex mathematical expressions using **MathJax** and **KaTeX**.
+
+https://squidfunk.github.io/mkdocs-material/reference/math/
+
+```markdown
+$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$
+
+Inline Equation: \(E=mc^2\)
+
+Exponents: \(x^2\)
+
+Square Root: \(\sqrt{x}\)
+
+Summation: \(\sum_{i=1}^{n} x_i\)
+
+Integrals: \(\int_{a}^{b} f(x) dx\)
+
+Greek Letters: \(\alpha, \beta, \gamma\)
+
+Matrices: 
+\[
+\begin{bmatrix}
+1 & 2 \\    
+3 & 4
+\end{bmatrix}
+\]
+
+Limits: \(\lim_{x \to \infty} f(x)\)
+
+Vector: \(\vec{v} = \langle v_1, v_2, v_3 \rangle\)
+
+Piecewise function:
+\[f(x) = 
+\begin{cases} 
+x, & \text{if } x \geq 0 \\
+-x, & \text{if } x < 0 
+\end{cases}
+\]
+
+Probability: \(P(A \cup B) = P(A) + P(B) - P(A \cap B)\)
+
+Derivatives: \(\frac{d}{dx} (x^2 + 2x + 1)\)
+
+Binomial Coefficients: \(\binom{n}{k}\)
+
+Trigonometric Functions: \(\sin(\theta)\), \(\cos(\theta)\), \(\tan(\theta)\)
+```
+
 ## Using tags
 
+To facilitate content search within your site, we recommend inserting a tag inside your Markdown files.
+With MkDocs Material, it's sufficient to add the following to your mkdocs.yml file:
+
+```markdown
+plugins:
+  - tags
+```
+
+Within the Markdown file where you want to add a tag, simply include this element in the metadata:
+
+```markdown
+---
+title: My title
+tags:
+    - mkdocs
+---
+```
+
 ## Neuteroi components
 
 **Neuteroi** is a library of add-ons for **mkdocs** that we loved and also used for our PythonBiellaGroup site.
@@ -181,6 +247,23 @@ Here is an example with the timeline:
 ::/timeline::
 ```
 
+Here is an example with the cards:
+
+```markdown
+
+::cards::
+
+- title: Bards
+  content: Lorem ipsum dolor sit amet.
+  image: https://upload.wikimedia.org/wikipedia/commons/f/f0/Google_Bard_logo.svg
+
+- title: ChatGPT
+  content: Lorem ipsum dolor sit amet.
+  image: https://upload.wikimedia.org/wikipedia/commons/thumb/0/04/ChatGPT_logo.svg/1024px-ChatGPT_logo.svg.png
+
+::/cards::
+```
+
 Of course we refer to the [official site](https://www.neoteroi.dev/mkdocs-plugins/timeline/) to see examples and different configurations
 
 ## Problems encountered

docs/learning/mkdocs_tutorial/extra_functions.md

@@ -139,8 +139,75 @@ extra_css:
 
 ## Scrivere equazioni scientifiche
 
+Con mkdocs material é possibile includere espressioni matematiche complesse tramite **MathJax** e **KaTex**
+
+https://squidfunk.github.io/mkdocs-material/reference/math/
+
+```markdown
+$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$
+
+Inline Equation: \(E=mc^2\)
+
+Exponents: \(x^2\)
+
+Square Root: \(\sqrt{x}\)
+
+Summation: \(\sum_{i=1}^{n} x_i\)
+
+Integrals: \(\int_{a}^{b} f(x) dx\)
+
+Greek Letters: \(\alpha, \beta, \gamma\)
+
+Matrices: 
+\[
+\begin{bmatrix}
+1 & 2 \\    
+3 & 4
+\end{bmatrix}
+\]
+
+Limits: \(\lim_{x \to \infty} f(x)\)
+
+Vector: \(\vec{v} = \langle v_1, v_2, v_3 \rangle\)
+
+Piecewise function:
+\[f(x) = 
+\begin{cases} 
+x, & \text{if } x \geq 0 \\
+-x, & \text{if } x < 0 
+\end{cases}
+\]
+
+Probability: \(P(A \cup B) = P(A) + P(B) - P(A \cap B)\)
+
+Derivatives: \(\frac{d}{dx} (x^2 + 2x + 1)\)
+
+Binomial Coefficients: \(\binom{n}{k}\)
+
+Trigonometric Functions: \(\sin(\theta)\), \(\cos(\theta)\), \(\tan(\theta)\)
+```
+
 ## Utilizzare i tags
 
+Per favorire la ricerca di contenuti all'interno del vostro sito vi consigliamo di inserire un tag all'interno dei vostri file markdown.
+Con mkdocs material é sufficiente inserire nel file mkdocs.yml:
+
+
+```markdown
+plugins:
+  - tags
+```
+
+All'interno del markdown per cui volete aggiungere un tag basterà inserire questo elemento nei metadati:
+
+```markdown
+---
+title: My title
+tags:
+    - mdkocs
+---
+```
+
 ## Componenti neuteroi
 
 **Neuteroi** è una libreria di componenti aggiuntivi per **mkdocs** che a noi ci è piaciuta tantissimo e che abbiamo utilizzato anche per il nostro sito di PythonBiellaGroup.
@@ -182,6 +249,22 @@ Qui un esempio con la timeline:
 ::/timeline::
 ```
 
+Qui un esempio con le cards:
+
+```markdown
+::cards::
+
+- title: Bards
+  content: Lorem ipsum dolor sit amet.
+  image: https://upload.wikimedia.org/wikipedia/commons/f/f0/Google_Bard_logo.svg
+
+- title: ChatGPT
+  content: Lorem ipsum dolor sit amet.
+  image: https://upload.wikimedia.org/wikipedia/commons/thumb/0/04/ChatGPT_logo.svg/1024px-ChatGPT_logo.svg.png
+
+::/cards::
+```
+
 Ovviamente rimandiamo al [sito ufficiale](https://www.neoteroi.dev/mkdocs-plugins/timeline/) per vedere esempi e differenti configurazioni
 
 ## Problemi riscontrati

docs/learning/mkdocs_tutorial/mkdocs_vs_sphinx.en.md

@@ -0,0 +1,25 @@
+---
+title: MkDocs vs Sphinx
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+    - sphinx
+---
+
+In the landscape of libraries for generating automatic documentation and static sites, we cannot fail to mention [Sphinx](https://sphinx-rtd-theme.readthedocs.io/en/stable/), which perhaps represented the Python standard until a few years ago.
+
+You can already find a reference to **Sphinx** and its features within this [article](../../learning/document_code/index.md).
+
+In this section, instead, we will schematically compare the characteristics of Sphinx and MkDocs to highlight the strengths of both.
+
+|                  | MkDocs                                     | Sphinx                                                                |
+| --------------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| `Supported Formats`   | **Markdown**                               | **reStructuredText (rST)** but with the myst-parser extension supports Markdown        |
+| `Startup`       | Easy with the command `poetry run mkdocs .` | Simple with the command `sphinx-quickstart`                          |
+| `Configuration`| Utilizes a YAML file **mkdocs.yml**        | Utilizes a Python file **conf.py**                                   |
+| `Layout`        | Elegant and appealing, also navigable     | Somewhat dated. The Read the Docs theme is iconic                     |
+| `Build`         | Provides a local server to fully test the site. Convenient command `poetry run mkdocs serve` | Generates the site build but the user must then test it in their browser. This is done with `make html` |
+| `Extensions`    | There are many but not all are maintained | There are many extensions but the community is less active compared to MkDocs |
+| `Customization` | Infinite possibilities thanks to CSS integration and available themes | Decidedly less customizable                                |
+| `Third-party Integration` | Integration with Confluence with this [extension](https://github.com/pawelsikora/mkdocs-with-confluence) | Integration with Confluence with this [extension](https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/) |

docs/meetup/archive/mkdocs/tutorial_1.en.md

@@ -21,7 +21,7 @@ In this first meeting, we will explore the fundamental aspects of MkDocs with pa
 | Wiki   | [PBG Learning](https://pythonbiellagroup.it/learning/mkdocs_tutorial/)|
 | Mkdocs material  | https://squidfunk.github.io/mkdocs-material/|
 | Github pages  | https://pages.github.com/|
-| Github actions | https://docs.github.com/en/actions|
+| Github actions | https://docs.github.com/en/actions |
 
 ## Meetup video
 

docs/meetup/archive/mkdocs/tutorial_1.md

@@ -21,7 +21,7 @@ In questo primo incontro vedremo gli aspetti fondamentali di mkdocs con particol
 | Wiki   | [PBG Learning](https://pythonbiellagroup.it/learning/mkdocs_tutorial/)|
 | Mkdocs material  | https://squidfunk.github.io/mkdocs-material/|
 | Github pages  | https://pages.github.com/|
-| Github actions | https://docs.github.com/en/actions|
+| Github actions | https://docs.github.com/en/actions |
 
 ## Video del meetup
 

docs/meetup/archive/mkdocs/tutorial_2.en.md

@@ -23,7 +23,7 @@ Main topics:
 | Wiki   | [PBG Learning](https://pythonbiellagroup.it/learning/mkdocs_tutorial/)|
 | Mkdocs material  | https://squidfunk.github.io/mkdocs-material/|
 | Github pages  | https://pages.github.com/|
-| Github actions | https://docs.github.com/en/actions|
+| Github actions | https://docs.github.com/en/actions |
 
 ## Meetup video