Skip to content

Home

Jump to bottom
Luise Freese edited this page Jul 25, 2022 · 17 revisions

Welcome to the Microsoft 365 Community Blog wiki!

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:

Preparing for your post

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:

  • Who are you writing this for?
  • 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

Writing your post

This blog is backed by a GitHub repository and all contributions are done by Pull requests.

Extensive guidance on how contributing works

If you feel like you need some more support with that, you can

  • Read the full Contributing guide (with step-bt-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.

tl;dr - how-to guidance for experienced GitHub users

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 (space))
  • In the newly created folder add an index.md file 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 images in your article’s folder. In the images folder you may save any image/graphic which may be used in your article

Publishing your post

  • Pull request your changes, targeting the main branch
  • 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.

Run Hugo locally

The Microsoft 365 Community blog uses Hugo, a static site generator.

What is Hugo?

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.

Installing Hugo on your PC

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.json file in the GitHub repository. (You'll find more info on the devcontainer further down this page.) At the time of writing we're at version 0.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.2

If 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=gohugoio

This string contains the version number and whether you've got the extended version: (look for the +extended string)

Using our devcontainer

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 if 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:

clone 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.

Running Hugo locally

Open a terminal in the root directory of your blog and run the following command:

hugo server

What 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.

Running the blog locally

Guidance on formatting and how to write good instructions

We collected some resources to improve your writing style

Clone this wiki locally