Home
This area covers topics related to creating content in the community blog. We'll add more content as we evolve this blog, but here is what we have so far:
We are looking for blog posts focusing on how to extend Microsoft 365 with custom-coded and low-code ways. Our audience spans a broad variety of developers and makers and we aim to empower them to build more with Microsoft 365. To prepare your post, it's a good idea to think about:
- For whom are you writing this?
- What is the use case/scenario for your solution?
- Does your approach contain a sample/pattern, that is potentially reusable? Can you include it?
Once you covered this, you can think about everything that will make it easier for people to comprehend your work:
- Overview-diagram that shows how different parts fit together
- Sample code
- Example
This blog is backed by a GitHub repository and all contributions are done by pull requests.
If you feel like you need some more support with that, you can
- Read the full Contributing guide (with step-by-step instructions)
- Sign up for our Sharing is Caring sessions, where we provide you with hands-on guidance on how to use GitHub, submit samples, contribute to documentation and more.
If you are already familiar with GitHub, please follow this high-level overview:
- Fork this repository https://github.com/pnp/blog
- Create a new branch that matches the article name that you want to write
- In the content/post folder, create your own folder (you may use the title of your post as the name of the folder, use
-(dash) instead of - In the newly created folder add an
index.mdfile with your article - Insert metadata at the top of this file and adjust with your values:
---
# This is the title
title: "this is the title of your blog post"
# This is the publishing date of your article, usually this should match "now"
date: 2022-04-25T08:40:00-04:00
# This is your name
author: "your Name"
# This is your GitHub name
githubname: yourGitHubUserName
# Don't change
categories: ["Community post"]
# Link to the thumbnail image for the post
images:
- images/myImage.png
# Don't change
tags: []
# Don't change
type: "regular"
draft: true
---- Create a new folder
imagesin your article’s folder. In the images folder you may save any image/graphic which may be used in your article
- Pull request your changes, targeting the
mainbranch - A maintainer will review, so that your article is published soon
If there are only minor changes necessary, like formatting or obvious typos, we will apply them and publish. In case there is some more extensive work to do still, a maintainer will request changes and help you resolve any issue.
The Microsoft 365 Community blog uses Hugo, a static site generator.
If you're not familiar with the term: It's a tool that can generate a website by converting markdown files and combining them with a template. Using a static site generator means you don't need a Content Management System, a database or a webserver with all kinds of requirements. You can just write files in Markdown and host your files anywhere. Static sites load very fast, and it's a great experience writing content in easy-to learn Markdown.
Now Markdown looks nice, but you never know for sure how it will be transformed without seeing it for yourself. If you want to know, you need to install and run Hugo locally.
More about Hugo.
To install Hugo you can follow the guidance in the Hugo docs. There are a few things to take note of:
-
Hugo extended: Make sure that you install Hugo extended. The PnP blog uses scss/css compilation, which is only available in extended.
-
Hugo Version: It's also best if you align with the version of Hugo that we use on the PnP blog. You can find the current version in the
.devcontainer/devcontainer.jsonfile in the GitHub repository. (You'll find more info on the devcontainer further down this page.) At the time of writing we're at version0.100.2.
Taking the above into account, the following script can be used to install Hugo with PowerShell on Windows. (using the Chocolatey package manager)
# Installs chocolatey if you don't have it
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
# Installs hugo
choco install hugo-extended --version=0.100.2If you already have Hugo installed, you can check the version running hugo version. It should print something like this:
hugo v0.100.2-d25cb2943fd94ecf781412aeff9682d5dc62e284+extended linux/amd64 BuildDate=2022-06-08T10:25:57Z VendorInfo=gohugoioThis string contains the version number and whether you've got the extended version: (look for the +extended string)
Installing Hugo on your system is OK if you don't mind. But maybe you have your own Hugo development going on, with separate versions of Hugo. Or maybe you don't like to install more programs, cluttering your system. It is possible to separate your contributions from the other stuff going on in your PC. This can be done using Docker. Using Docker is like running a VM on your PC, and being able to clean it up instantly when you're done. It's an advanced subject, but for the matter at hand you need three things:
Once you have them all installed and Docker running, open a new VS Code window, open the Command Palette using Ctrl + Shift + P and search for the command Clone repository in Container Volume:
The command will ask for a git URL, and you can copy/paste our git url there: https://github.com/pnp/blog.git. Following the prompts and hitting enter will start cloning the repository on your machine in a completely separated docker volume. It will also install Hugo, so you'll not need to do anything else after.
This is a VERY condensed way to explain it. If you're interested in finding out a bit more, you can read up on remote containers or follow the tutorial.
Open a terminal in the root directory of your blog and run the following command:
hugo serverWhat this will do is build the site and start a server that will allow you to view the site using the URL http://localhost:1313/blog/. It will also configure a watcher, so any changes you make to md-files are instantly compiled. No need to hit F5 after, your browser window will be refreshed for you as well.
The site makes heavy use of Hugo's image processing feature to resize all content images into multiple responsive sizes. These are used for content pages as well as the thumbnail cards of the articles used in rollup areas (homepage, tag/category list pages, 'recent posts' sidebar, etc).
This process takes a long time and can time out when you build the site the very first time. If this happens, retry the build a few times. Hugo-generated images are saved to the ./resources/_gen/images/**/*.* folder. It might take 2-5 tries before the build works. The first build takes the longest... possibly up to, or exceeding, 5 minutes. In fact, our automated site builds can take 10-20 minutes.
To be clear, THIS IS EXPECTED.
Once the files are generated, in future builds, Hugo will see the file is already present & not re-generate it, greatly reducing build times.
We collected some resources to improve your writing style