We will explain how you can contribute to the devblog.
Topics
- Overview
- Writing a Post
- Deployment
- Future
Thank you
If you are reading this, you are thinking of contributing, so you are already half way there 😉. A blog only survives by the quality and volume of content, so scalability and diversity of content are key.
“But why will I contribute, tomorrow we move to another platform and everything is lost” - Well, this is a legitimate concern, in the past we had this happen to us, when we relied on proprietary systems to store our information, only to later realize exporting information was a major hassle. But fret not, this time we use markdown for all this content, so if tomorrow we want to move to an even better platform due to having so much content and contributors, we can just tweak a bit and use as is.
Overview
The DevBlog is built in hugo, using a template heksagon. The source code resides in DevDocs under the folder DevBlogPortal.
In order to start locally the blog, install hugo in a powershell run choco install hugo-extended, then simply clone the repository, open a command shell in the folder DevBlogPortal and run hugo serve. This is very helpful to validate how your post looks before commiting the changes, you can also perform edits while the server runs and it will refresh automatically.
The important folders for contributors are the DevBlogPortal/content/blog here is where you will create new contributions are write the markdown for your blog post and DevBlogPortal/static/blogPosts here is where all static content will reside (i.e images).
Note: Please use videos/gifs with moderation as they cumulatively consume a lot of space.
Writing a Post
To write the markdowns there are a lot of available markdown editors, what was used to write this post as VSCode, VSCode has a preview mode for markdown.
In order to write a new post go to DevBlogPortal/content/blog and create a new markdown file with the name <yearmonthday>_<areaofinterest>_<yourpost> (i.e 20230413_iot_mes_as_configuration_owner). It’s very important your markdown has the following header:
---
author: <authorname>
title: <title>
date: <yearmonthday>
description: <description
tags: [<tag1>,<tag2>]
categories: [<category1><category2>]
ShowToc: true
TocOpen: true
---
It’s very important you add relevant tags and categories as the template we are using, offers a very powerful search based on tags and categories, and as the number of post grows it is a very easy way to sort and search.
We also strongly incentivize for you to add a footer
<br></br>
---
<br></br>
## Author
### <Small text saluting the reader and explaining who you are and how they can reach you>
Skills: <particular focus or areas of interest you have>
<image of yourself (use your cmf photo if possible) this photos should be added under `DevBlogPortal/static/blogPosts/contributors`>
Things to look out for
The least intuitive thing, is that for images, the path for deployment and for preview here in your markdown editor are different. For example, it would be intuitive to say that an image is under DevBlogPortal/static/blogPosts/contributors/johnDoe.jpg, but when hugo deploy this path will not have meaning, you should use /blogPosts/contributors/johnDoe.jpg. Nevertheless, you can use hugo serve in order to see how the site will render.
When you’ve finished writing your post and are happy with the result, create a Pull Request against the branch DevDocs. Someone from the DevDocs team will revise your post and perform the deployment.
Future
The CMF CLI already has a cmf doc-gen, so why not add a doc-gen for the blog, that creates this structure! As more contributors join, we get their feedback and understand how needed is this type of tooling.
Author
Hello 👏 , my name is João Roque ✌️
I’ve been working for some years at Critical Manufacturing. I split my time working in the IoT Team and working with the project’s teams. You can visit me at https://j-roque.com/ or check me at LinkedIn
Skills: Connect IoT / DevOps