SR Linux Blog Launch#

Openness, extensibility, innovation and community focus make a large part of the Nokia SR Linux core. Mix it up with our engineering background and you get a resource where we share technical content in the engineers-to-engineers fashion.

Today we would like to take it one step further and augment the learn.srlinux.dev portal with a community blog section where Nokia engineers and our community members can post content relevant to modern network technologies.

This blog post explains how to contribute a blog article to our portal and what visual candies you can use to make your post look awesome.

Creating a blog post#

Did you decide to contribute a blog post? That's great. Here is what you need to do.

1. Create a file under ./docs/blog/posts/<year>/<your-filename>.md. A <year> is in the YYYY format and stands for the year the post was authored. The filename you choose for your post is completely up to you and doesn't affect a URL or title of the blog post.
2. Write Use the classic markdown syntax and optionally apply our advanced styling for visual dominance.
3. Add a date to the post metadata.
4. Add yourself as a new author if this is your first contribution.
5. Create a new git branch and commit your post.
6. Check how your article looks using the live web server started with the make serve-insiders target¹.
7. If all looks great, raise a PR with your work so we can review and merge it.
8. Profit!

Authors#

We want to give credit to the authors. To make yourself known to the community, please add an entry with your information to the .authors.yml file that lists authors. Once added, you can add yourself to the frontmatter of the blog post:

---
authors:
  - rdodin #(1)!
---

1. rdodin is a key used in the .authors.yml file for a particular authors. Multiple authors can be added to the list of authors

Styling#

This portal uses the famous mkdocs-material documentation theme. This theme packs a lot of UX improvements on top of classic markdown syntax. Knowing how to use those additional elements can make your post look awesome both from visual and user experience angles.

We would like to highlight a few UI elements we use all the time and hope you'll also like them.

Tabs#

Tabs help to visually organize the content and improve readability an awful lot.

=== "C"

    ``` c
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++"

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

Code#

Nowadays, code is everywhere. With a few styling aids you can make your code blocks look shart and expressive.

A regular code block with a syntax highlighting uses code fences style:

``` py
import tensorflow as tf
```

import tensorflow as tf

Title#

To add a title to a code block, use the title attribute:

``` py title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Line numbers#

Line numbers can be added to a code block by using the linenums="<start>" option directly after the shortcode, whereas <start> represents the starting line number. A code block can start from a line number other than 1, which allows to split large code blocks for readability:

``` py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

1
2
3
4
5

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Highlighting specific lines#

Specific lines can be highlighted by passing the line numbers to the hl_lines argument placed right after the language shortcode. Note that line counts start at 1, regardless of the starting line number specified:

``` py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

1
2
3
4
5

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Annotations#

Code annotations can be placed anywhere in a code block where a comment for the language of the block can be placed, e.g. for JavaScript in // ... and /* ... */, for YAML in # ..., etc.:

``` yaml
theme:
  features:
    - content.code.annotate # (1)!
```

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

theme:
  features:
    - content.code.annotate # (1)!

Admonitions#

Admonitions is a great way to emphasize a piece of information. Check the original documentation for all the customizations available for admonitions.

!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Icons#

Our doc theme includes a gazillion of icons and emojis which are super easy to use. Use the search tool to find the icon code-block and paste it in your post.

:smile: 

Footnotes#

Footnotes are a great way to add supplemental or additional information to a specific word, phrase or sentence without interrupting the flow of a document. Material for MkDocs provides the ability to define, reference and render footnotes.

A footnote reference must be enclosed in square brackets and must start with a caret ^, directly followed by an arbitrary identifier, which is similar to the standard Markdown link syntax.

Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

The footnote content must be declared with the same identifier as the reference. It can be inserted at an arbitrary position in the document and is always rendered at the bottom of the page. Furthermore, a backlink to the footnote reference is automatically added.

on a single line#

Short footnotes can be written on the same line:

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

on multiple lines#

Paragraphs can be written on the next line and must be indented by four spaces:

[^2]:
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Subscribing#

Get notified when a new post is published using one of the subscription options offered.

Comments