From f41f79ba55a82e974ebc40f7a8bf69c970b08c67 Mon Sep 17 00:00:00 2001 From: Davide Airaghi Date: Sat, 17 Feb 2024 19:30:39 +0100 Subject: [PATCH] add mdkocs tutorial content --- README.md | 2 +- docs/blog/index.md | 3 + docs/blog/posts/new_brand_identity.en.md | 3 + docs/blog/posts/new_brand_identity.md | 3 + .../mkdocs_tutorial/extra_functions.en.md | 83 +++++++++++++++++++ .../mkdocs_tutorial/extra_functions.md | 83 +++++++++++++++++++ .../mkdocs_tutorial/mkdocs_vs_sphinx.en.md | 25 ++++++ docs/meetup/archive/mkdocs/tutorial_1.en.md | 2 +- docs/meetup/archive/mkdocs/tutorial_1.md | 2 +- docs/meetup/archive/mkdocs/tutorial_2.en.md | 2 +- docs/meetup/archive/mkdocs/tutorial_2.md | 3 +- docs/speakers/index.en.md | 2 +- docs/speakers/index.md | 2 +- mkdocs.yml | 3 + templates/blog_post.md | 18 ++++ templates/meetup.md | 32 +++++++ 16 files changed, 261 insertions(+), 7 deletions(-) create mode 100644 docs/learning/mkdocs_tutorial/mkdocs_vs_sphinx.en.md create mode 100644 templates/blog_post.md create mode 100644 templates/meetup.md diff --git a/README.md b/README.md index 884a282..f1daabc 100644 --- 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 index ece2777..3db410d 100644 --- 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 index 6e41f16..1932d95 100644 --- 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 index 1757306..e3cad7a 100644 --- 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 index bf10d5b..8592bfd 100644 --- 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 index 6d237a0..d20ef09 100644 --- 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 new file mode 100644 index 0000000..a388ac1 --- /dev/null +++ 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/) | \ No newline at end of file diff --git a/docs/meetup/archive/mkdocs/tutorial_1.en.md b/docs/meetup/archive/mkdocs/tutorial_1.en.md index 5c0bc83..4855c58 100644 --- 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 index c4f8137..5aa5adb 100644 --- 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 index 22696ed..513220e 100644 --- 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 index 13c1a19..a6c76ed 100644 --- 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 \ No newline at end of file diff --git a/docs/speakers/index.en.md b/docs/speakers/index.en.md index 93e8438..f9686f2 100644 --- 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 index a061bda..d2d35be 100644 --- 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 index 2da662e..5b3282e 100644 --- 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 new file mode 100644 index 0000000..459d0cd --- /dev/null +++ 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. \ No newline at end of file diff --git a/templates/meetup.md b/templates/meetup.md new file mode 100644 index 0000000..78246ac --- /dev/null +++ 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 \ No newline at end of file