Merge pull request #15 from PythonBiellaGroup/develop

add mdkocs tutorial content
PythonBiellaGroup · Feb 17, 2024 · cf08b5c · cf08b5c
2 parents b0d3c04 + f41f79b
commit cf08b5c
Show file tree

Hide file tree

Showing 16 changed files with 261 additions and 7 deletions.
diff --git a/README.md b/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

diff --git a/docs/blog/index.md b/docs/blog/index.md
@@ -1,5 +1,8 @@
 ---
 exclude_from_blog: true
+hide:
+  - toc
+  - feedback
 ---
 
 # Blog

diff --git a/docs/blog/posts/new_brand_identity.en.md b/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

diff --git a/docs/blog/posts/new_brand_identity.md b/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

diff --git a/docs/learning/mkdocs_tutorial/extra_functions.en.md b/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

diff --git a/docs/learning/mkdocs_tutorial/extra_functions.md b/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

diff --git a/docs/learning/mkdocs_tutorial/mkdocs_vs_sphinx.en.md b/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/) |
diff --git a/docs/meetup/archive/mkdocs/tutorial_1.en.md b/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
 

diff --git a/docs/meetup/archive/mkdocs/tutorial_1.md b/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
 

diff --git a/docs/meetup/archive/mkdocs/tutorial_2.en.md b/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
 

diff --git a/docs/meetup/archive/mkdocs/tutorial_2.md b/docs/meetup/archive/mkdocs/tutorial_2.md
@@ -23,7 +23,8 @@ Argomenti principali
 | 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
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/mbT5xptiYOo?si=GSIslUeiknjGOqJf" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
diff --git a/docs/speakers/index.en.md b/docs/speakers/index.en.md
@@ -2,7 +2,7 @@
 title: Participate as a speaker
 disquis: PythonBiellaGroup
 tags:
-  - speaker
+  - speakers
 hide:
   - feedback
 ---

diff --git a/docs/speakers/index.md b/docs/speakers/index.md
@@ -2,7 +2,7 @@
 title: Partecipa come speaker
 disquis: PythonBiellaGroup
 tags:
-  - speaker
+  - speakers
 hide:
   - feedback
 ---

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -549,6 +549,9 @@ plugins:
                     Come costruire un agente intelligente: Building an intelligent agent with LangChain, Gradio, and OpenAI
                     Elementi principali di mkdocs: Main elements of mkdocs
                     Extra, plugins e deploy del sito: Extra, plugins and site deployment
+                    Estensioni: Extensions
+                    Funzionalità extra: Extra functionalities
+
     - git-revision-date-localized
 
 #Extra material theme settings

diff --git a/templates/blog_post.md b/templates/blog_post.md
@@ -0,0 +1,18 @@
+---
+title: Titolo dell'articolo
+description: Descrizione dell'articolo
+comments: true
+timetoread: true
+tags:
+ - tag 1
+ - tag 2
+hide:
+  - toc
+  - feedback
+---
+
+# Titolo
+
+![Logo](../../static/images/blog/la_tua_immagine.jpeg)
+
+Corpo dell'articolo.
diff --git a/templates/meetup.md b/templates/meetup.md
@@ -0,0 +1,32 @@
+---
+title: Your title
+disquis: PythonBiellaGroup
+tags:
+    - your tag
+---
+
+## Intro
+
+Scrivi una breve introduzione al meetup.
+
+## Materiale
+
+Se é disponibile solo la repo github usa il badge qui sotto:
+
+[![Github](https://img.shields.io/badge/GitHub-181717.svg?style=for-the-badge&logo=GitHub&logoColor=white)](github link)
+
+Se ci sono più cose da condividere, puoi utilizzare una tabella come questa:
+
+
+|          | Link     | 
+|----------|----------|
+| Repo     | [![Github](https://img.shields.io/badge/GitHub-181717.svg?style=for-the-badge&logo=GitHub&logoColor=white)](github link)|  
+| Slides   | Url alle slide |   
+
+## Video del meetup
+
+Incorpora qui l'iframe del video pubblicato su youtube facendo:
+
+1. Clicca su condividi
+2. Seleziona **Incorpora**
+3. Copia l'iframe e incollalo qui