Skip to content

Blog

Azure Services

I have decided to create a new category on my blog to talk about Azure services.

The main goal of this category is to provide a quick overview of some Azure services and some design considerations.

What is this category due to?

In some cases, it is because I am working with this Service and I think it is a good idea to share my experience with you and write it down for me, in others, it is because I am studying/reviewing an Azure Service and I think it is a good idea. Share my notes with you.

I hope you like it.

I am going to start with Azure Communication Services

That's all folks!, thanks for reading ❤!

Starting to develop in c#

First, I need to clarify that I'm not a C# developer. I'm learning C# so I can better understand the code that has to be deployed to some Azure services when .NET is used.

If someone that knows me is reading this post, he/she will be thinking:

  • "What the hell is he doing?"
  • "He is crazy"
  • "He is going to die trying".
  • The end of the world is approaching!!

Maybe the last thought can be really true but I have to say that I have decided to learn a programming language and that I have chosen C# because many of the examples for Azure Developers that I have seen are written in C#.

I repeat, I am not a developer but I'd like to share with you my experience learning C#.

My first Steps

You have a lot of resources for learning on Learn .NET and in c# documentation.

In my case I prefer to simplify and follow csharp-notebooks, these materials are designed to be used with C# 101 SERIES.

After that, I will follow the free course (New) Foundational C# with Microsoft.

And after that, I think that I will be ready to start with Tutorials for getting started with .NET and plan next steps.

That's all folks!!

Trunk

What is Trunk ?

Trunk is a tool that runs a suite of security and best practice checks against your code. It is designed to be used in CI/CD pipelines, but can also be used as a standalone tool.

Support for the following languages is currently available:

Installing Trunk

curl https://get.trunk.io -fsSL | bash

code --install-extension Trunk.io

Trunk checks

Trunk checks cli

Trunk detects checks to enable in function of the files in the current directory, but you can also enable and disable checks manually.

  • trunck check list: list all available checks
  • trunck check enable checkname: enable a check
  • trunck check disable checkname: disable a check
  • trunck check: run all enabled checks

For example, to enable the Terraform check:

trunk check enable terraform 
1 linter was enabled:
  terraform 1.1.0

Info

You can also enable checks by modifing .trunk.yml file in your repository. See the configuration page for more information.

Examples:

trunk commnad line check example
trunk check   

Checking 68% [====================================================================================================================================================================>                                                                              ]  38/56  9.4s 
 ↳ checkov                                                                                                                                                                                                                                                                      
   ↳ modules/webapps/linux_function_app/private_endpoint.tf [lint] ⠧                                                                                                                                                                                                            
   ↳ modules/webapps/linux_function_app/variables.tf [lint] ⠧                                                                                                                                                                                                                   
 ↳ terrascan                                                                                                                                                                                                                                                                    
   ↳ modules/webapps/linux_function_app/locals.tf [lint] ⠧                                                                                                                                                                                                                      
   ↳ modules/webapps/linux_function_app/main.tf [lint] ⠧

Trunk checks vscode

In the case of the VSCode extension, you can review your checks in your IDE:

Trunk checks vscode

And you can disable checks from quick fix menu:

Quick Fix

Trunk updates

Trunk updates cli

Trunk is updated regularly with new checks and improvements. You can update Trunk by running the following command:

trunk update

Trunk updates vscode

In the case of the VSCode extension, it will be updated automatically:

Trunk updates

References

Enhance your mkdocks.yml

In the previous post I explained how to create a blog with MkDocs and mkdocs-material theme.

mkdocs.yml is the configuration file for MkDocs. In this file we can configure the theme, the plugins, the pages, etc.

In this post I am going to explain you how to create a blog with MkDocs and mkdocs-material theme, add some plugins and configure it.

Minimal configuration for mkdocs.yml with mkdocs-material

site_name: My Site
theme: 
  name: material
#plugins:

#markdown_extensions:

Theme

I only change the palette for now.

theme: 
  name: material
  palette:
    primary: blue
    accent: white

Plugins for mkdoc

glightbox

glightbox add image zoom functionality to your documentation.

requirements.txt
mkdocs-glightbox
mkdocs.yml
plugins:
  - glightbox

Example:

Amigos de fiesta

Imagen de marymarkevich en Freepik

mkdocs-minify-plugin

An MkDocs plugin to minify HTML, JS or CSS files prior to being written to disk.

requiremets.txt
mkdocs-minify-plugin

Extensions

Material for MkDocs

MkDocs supports a large number of Python Markdown extensions

mermaid

mermaid2 is a plugin for MkDocs that allows you to embed diagrams written in mermaid.js in your Markdown documentation.

mkdocs.yml
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
Example
  ```mermaid
  graph LR
      A[Square Rect] -- Link text --> B((Circle))
      A --> C(Round Rect)
      B --> D{Rhombus}
      C --> D
  ```

graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D

You can find more information about mermaid.js in https://mermaid-js.github.io/mermaid/#/

Admonitions

Admonitions is a markdown extension of materials for MkDocs that allows you to add admonition blocks to your Markdown documentation.

mkdocs.yml
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Example:

!!! Example
    Example
!!! Error
    Error
!!! Warning
    Warning    
!!! Success
    Success
!!! Info
    Info    
!!! Tip
    Tip
!!! Question
    Question
!!! Quote
    Quote

Example

Example

Error

Error

Warning

Warning

Success

Success

Info

Info

Tip

Tip

Question

Question

Quote

Quote

Icons, Emojis

With material you can use more than 10000 icons and thousand of emojis in your documentation.

mkdocs.yml
markdown_extensions:  
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Example:

:smile:
:man_head:
:face_with_monocle:
:jack_o_lantern:

😄 🙋‍♂️ 🧐 🎃

Annotations

One of the flagship features of Material for MkDocs is the ability to inject annotations – little markers that can be added almost anywhere in a document and expand a tooltip containing arbitrary Markdown on click or keyboard focus.

mkdocs.yml
markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.superfences

Examples:

This is a paragraph with a annotation(1).
{ .annotate }

1.  :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
    text__, images, ... basically anything that can be expressed in Markdown.

This is a paragraph with a annotation(1).

  1. 🙋‍♂️ I'm an annotation! I can contain code, formatted text, images, ... basically anything that can be expressed in Markdown.
This is a paragraph with a annotation(1).
{ .annotate }

1.  :man_raising_hand: I'm an annotation! with a nested annotation(1)
    { .annotate }

    1. I'm a nested annotation!

This is a paragraph with a annotation(1).

  1. 🙋‍♂️ I'm an annotation! with a nested annotation(1)

    1. I'm a nested annotation!

Buttons

mkdocs.yml
markdown_extensions:
  - attr_list

Examples:

[This is a button](#)
{ .md-button }

This is a button

[This is a button](#)
{ .md-button .md-button--primary }

This is a button

[Send :fontawesome-regular-face-laugh-wink:](#){ .md-button }

Send

Content tabs

mkdocs.yml
markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

Example:

=== "azcli"

    ``` azcli    
    az group create --name myResourceGroup --location westeurope
    ```

=== "pwsh"

    ``` pwsh    
    New-AzResourceGroup -Name myResourceGroup -Location westeurope    
    ```
bubble_sort.py
az group create --name myResourceGroup --location westeurope

New-AzResourceGroup -Name myResourceGroup -Location westeurope

Footnotes

mkdocs.yml
markdown_extensions:
  - footnotes

Example:

This is a paragraph with a footnote[^1].

[^1]: And here is the definition.

This is a paragraph with a footnote1.

Formatting

mkdocs.yml
markdown_extensions:
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde

Example:

- ~~Mistaken text.~~
- ^^Superscript^^
- ==Marked text.==
  • Mistaken text.
  • Superscript
  • Marked text.

mkdocs.yml complete

site_name: My Site
site_description: A blog about Azure, DevOps and other stuff
site_author: Rafael Fernández
site_url: https://rfernandezdo.github.io

theme: 
  name: material
  palette:
    primary: blue
    accent: white
  features:
    - navigation.tabs
    - navigation.expand
    - navigation.sections
    - toc.integrate
    - toc.nested
    - toc.smoothscroll
    - footer
    - content.code.copy
    - content.code.annotate
    - content.tooltips
extra:
  social:
    - icon: fontawesome/brands/linkedin
      link: https://www.linkedin.com/in/rafaelfernandezd/
      name: LinkedIn
    - icon: fontawesome/brands/github
      link: https://github.com/rfernandezdo
      name: GitHub
    - icon: fontawesome/solid/square-rss
      link: https://rfernandezdo.github.io/feed_rss_created.xml
      name: RSS feed
copyright: Copyright © 2023-now Rafael Fernández

plugins:
  - search  
  - mermaid2
  - blog  
  - tags:
      tags_file: tags.md    
  - rss:
      match_path: blog/posts/.* 
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
          remove_comments: true
      cache_safe: true
  - glightbox:
      zoomable: true
      draggable: true
      skip_classes:
        - skip-lightbox
    #- meta in insiders, review in next release
  - social
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - md_in_html
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - footnotes
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true

urls for reference

  1. And here is the definition. ↩↩↩

Create a blog with MkDocs,mkdocs-material, mkdocs-rss-plugin and GitHub Pages

A few time ago I maintained a blog with Wordpress. I was happy with it, but I wanted to try something new.

I tried Jekyll but it didn't convince me, I discovered mkdocs so I decided to use MkDocs and mkdocs-material. I was happy with the result, so I decided to write this post to explain how to create a blog with MkDocs, mkdocs-material and some plugins.

These is the first post of a serie of posts to create a blog with MkDocs, mkdocs-material and GitHub Pages and some customization.

Some knowledge:

  • MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

  • Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. It is built using Google's Material Design guidelines. Material for MkDocs provides a polished and responsive experience out of the box, and it is as easy to use for the beginner as it is for the seasoned developer.

  • GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website. You can see more information about GitHub Pages here.

  • This plugin generates an RSS feed for your MkDocs site. You can see more information about mkdocs-rss-plugin here.

Steps to deploy

Create a new repository

Create a new repository on GitHub named username.github.io, where username is your username (or organization name) on GitHub. If the first part of the repository doesn’t exactly match your username, it won’t work, so make sure to get it right.

Enable GitHub Pages on your repository

Go into the repository settings and, if you are not using GitHub Pages already, enable GitHub Pages on the gh-pages branch.

Clone the repository

Go to the folder where you want to store your project, and clone the new repository:

git clone ssh://github.com/username/username.github.io
cd username.github.io

Create requirements.txt in root folder for mkdocs, mkdocs-material and plugins

mkdocs==1.5.3
mkdocs-material==9.4.6
mkdocs-rss-plugin==1.8.0

Create a Python Virtual Environment and install requirements.txt

In username.github.io$ path:

sudo apt update
sudo apt install libcairo2
sudo apt install python3.10-venv
python3 -m venv mysite
source mysite/bin/activate
pip install -r requirements.txt

Initialize your site

mkdocs new .

Add configuration to mkdocs.yml in root folder

For this post I am going to add the following configuration:

  • basic configuration
  • configuration for theme mkdocs-material
  • some native plugins of mkdocs-material and some ones that I like
site_name: My Site 
site_description: A blog about Azure, DevOps and other stuff
site_author: Rafael Fernández

theme: 
  name: material
  features:
    - navigation.tabs
    - navigation.expand
    - navigation.sections
    - toc.integrate
    - toc.nested
    - toc.smoothscroll
    - footer

plugins:
  - search  
  - blog
  - tags:
      tags_file: tags.md      

  - rss:
      match_path: blog/posts/.* 
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags

Add a new post

In blog/post folder create a new folder with the name of the post and create a new file with the name of the post and the extension .md. For example: welcome.md 

---
date: 2023-10-18
categories:
  - Hello
  - World
---

# "Hello world!!!" from mkdocs-material

...

Check your site

In username.github.io$ path:

mkdocs serve

You can check your site in http://127.0.0.1:8000/ and make live changes in your site and see the results in your browser.

Publish your site

In username.github.io$ path:

mkdocs gh-deploy

After a seconds, you can check your site in https://username.github.io/

Automate deploy with GitHub Actions

name: ci # (1)!
on:
  push:
    branches:      
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install -r requirements.txt # (4)!
      - run: mkdocs gh-deploy --force

  1. You can change the name to your liking.

  2. At some point, GitHub renamed master to main. If your default branch is named master, you can safely remove main, vice versa.

  3. Store the cache_id environmental variable to access it later during cache key creation. The name is case-sensitive, so be sure to align it with ${{ env.cache_id }}.

    • The --utc option makes sure that each workflow runner uses the same time zone.
    • The %V format assures a cache update once a week.
    • You can change the format to %F to have daily cache updates.

    You can read the [manual page] to learn more about the formatting options of the date command.

  4. Add [MkDocs plugins] or Markdown extensions with pip to requirements.txt to be used during the build.

In the next post I will explain how to customize your site with mkdocs-material and some plugins writing mkdocs.yml.

That's it folks

urls for reference