Microsoft 365 Community SharePoint, 8 Jun 2023

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Build your own Documentation Website with DocFX on SharePoint

Description

In this 14-minute developer-focused demo Martin Heusser brings viewers up to speed on the DocFX tool. Why is it awesome, setup challenges, and where a DocFx generated static website is hosted? Dive in and clone his repo, create project and generate out-of-box site. Then, run Initialize-AwesomeDocFx.ps1 script that yields a more robust site. Add docs/images. Want your site on SPO? Run BuildDocFxForSPO.ps1, create a document library, compare and upload new files. Process Recap – define doc categories, initialize DocFx project, author documentation, preview locally, publish.

This PnP Community demo is taken from the Microsoft 365 & Power Platform Development Community call recorded on June 8, 2023.

Demo Presenter
• Martin Heusser (Houlihan Lokey) | @mozzeph

Community Call Conversation
• aka.ms/June8-Demo3

Supporting materials
• Documentation – docfx Quick Start | https://dotnet.github.io/docfx/
• Organization - .NET Foundation | https://dotnetfoundation.org/
• Organization - Microsoft Learn. Spark possibility | https://learn.microsoft.com
• Documentation - Awesome Docs | https://delightful-bush-073e2f403.3.azurestaticapps.net/index.html
• Repo – Docs (template) | https://github.com/mozziemozz/awesome-docfx-template

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/community/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/community/videos
• Microsoft 365 Platform Community - http://aka.ms/community/home

A

B

Which is near Zurich in Switzerland, Switzerland I'm, a Microsoft 365 apps and services MVP, and on the right side, you can see some of my favorite Technologies I like to work and Tinker with So. Today we're going to talk about dark effects and why it's awesome.

A

B

What are kind of the the challenges or the Stepping Stones to get started with working with this tool? What did I do to make it easier for you to get started if you've never worked with it before and we're going to talk about where you can host a dock of apps generated website and, of course, there will be a demo time.

B

These are the technologies that that have been used in this project. We've got SharePoint online doc effects Powershell and the awesome PMP Powershell module, which is really helpful for all things: SharePoint online and Powershell. So uh dock effects, it's a open source, static website generator, which is maintained by the.net foundation and the way it works.

B

Is you basically have some markdown files, which are just plain text files with some very light and easy to learn, syntax, which, in the end generates HTML files or a website containing HTML files from set markdown files, and the output you'll see, will look very similar to what you can see, for example, on learn about microsoft.com or also many other documentation websites out there?

B

uh Why I think it's an awesome tool or why documenting in markdown is one of the best things ever? Is that you get a single source for all of your docs?

B

You can change all the you track, all the changes with Git, no matter if they're stored in a GitHub repo or in Azure devops repo or whatever skit repository you use, you'll be able to track all the changes and contact content is always in plain text, so it's very easy to migrate it to another tool to another solution or whatever you can easily manipulate the text.

B

For example, if you have like a name change or something else like IP addresses or whatever changes inside your technical documentation, just read the files into a memory with Powershell and you can manipulate, replace and do everything in an automated way. Instead of going through each document manually, um you can do a continuous integration, continuous deployment. If you set that up later, once you build the site and it's just a very great user experience.

B

If uh consumers of that documentation can read and learn about your product or about your internal I.T environment, on a website, so they'll have search functionality, they'll be able to create and share links to articles or even two sections within articles and all that stuff and if you're a little bit more advanced with markdown. You can also reuse content across different articles.

B

So if you have like sections which are always going to be the same, and you could just reference that part- and you only need to change it in in one file, if something changes the so I've been working with dock effects for a couple of years now, I'm building my own documentation websites and there is a learning curve for markdown syntax.

B

So you have to learn how you can create titles tables, how links work and everything, and you also need to take a look at the anal structure like this- is where you create the table of content files, so that every or all the links of your website work properly and you'll have to figure out how to fold the structure inside your project works.

B

And, of course, if you want to publish that website anywhere, you'll need to you'll need some basic web hosting or service skills to get that website published now, um because of all these challenges, I initially faced I decided to create some Powershell scripts, which will greatly help you to get started.

B

So, instead of just creating a vanilla, dark effects project, you can use script to generate a pre-populated folder structure from a CSV, so you'll be able to Define your categories and subcategories and everything and the folder structure, all the ml files, all the references and everything will be automatically created for You by The Script and there's also script to upload and update that content.

B

If you decide to put your doc effects page on SharePoint online and then as an experiment, I'm also working on some partial functions to just make the certain things a little bit easier like creating links to images and stuff like that, I'll show that in the demo as well, so it's in the end once you've generated the site, it's just a static website, so you can host it on any web server really and you can put it on GitHub, Pages or Azure app service, static, web app or even SharePoint online with a few tweaks.

B

That's what I'm going to show you um if you decide to put it on SharePoint you'll, have no additional hosting fees, because you don't need a server and you'll have built-in authentication from Azure ID already, and you can use your uh or leverage your existing permission. Structures like if you have a team and the team already has members, there's no need to um assign more permissions or whatever and one of the coolest coolest things is that your documentation content will be indexed and searchable across all Microsoft, 365, apps or even Windows start when you search.

B

If you have that setup as well, so let's go to the repository, so everything is available on GitHub. You can just clone the repository and there's also a accompanying documentation website them. I'll show that later, if we still have time so once you've cloned the repository from GitHub, it will look like this. We have a few folders and we have a some some Powershell scripts uh in these, but first I want to show you how it would look like if you decide to just um create a vanilla project with Doc FX.

B

um So you uh on on the docs website, I just mentioned everything is noted. What tools you need to install and everything. Of course, I already have everything pre-installed for the demo. So we do it like this, just um doc effects in it and then specify the output folder, and this will generate the project under the docs folder and now you can see there are some markdown files which sends gamma files and stuff.

B

But what I want to show you is how that looks in the web browser if we decide to serve that website locally and preview it. So this is going to create a side folder, which is the output, which is also what you would put on a server.

B

Now you can see there is not much on there, that's just how it works when, when you get started with dark effects, so you need to figure out everything yourself if you're not using um my script, so it's pretty empty and we just have to categories here in in the horizontal nav bar.

B

Let's close that go back here and we can delete this folder again now there is a structure uh structure, CSV file you can put in all the categories you will want to have in your documentation, so this is kind of or kind of assumes you want to document your internal uh it environment or Cloud environment. So you have a couple of azure stuff in here: Microsoft 365, with subcategories of Team SharePoint exchange Etc, uh so yeah.

B

Let's just go to um our initialize doc effects and script, which is the script that will create the doc effects project for us, we'll have to give it a name. Let's just call that Demo Box, that's the only parameter, that's needed, and now you can see it created a docs folder again. But if I search that page we'll see that it's already way more uh content in there.

B

Browser and now we can see all the categories we have for subcategories. We have them structured in sub menus, which can be expanded and collapsed, and there is like a demo or an empty file in for each category. So we have the breadcrumbs as well uh yeah. um Now, let's say we don't want this call first party. We don't need that. So what we can do is just close. The server repeat the folder again go back to our CSV. Remove that line and regenerate the whole thing.

B

Then search that again, so you can do this as many times as you like until you're happy with the structure you laid out now you can see the consoles uh menu is gone.

B

Now, um under the the build folder there is another script called build dockfx for SharePoint online, and this is a script which uses uh the PMP partial module. And if we go back to docs and site, we can see that we have all these HTML files. So basically for every article there is a HTML file. So all the markdown was converted to HTML and the thing with SharePoint online is that it doesn't support HTML. It needs to be aspx.

B

There are a couple of blog posts out there, which mention that you need to rename them and that's basically what um this script does. Is it renames all the HTML file to aspx, so they can run interactively on SharePoint now, I'm going to run that script, which will keep the same. It will build the website again and then all the files will be renamed.

B

Now it will start uploading to SharePoint online, but it can actually.

B

Stop that, because, for the sake of the demo, I've already uploaded everything, so uh we don't have to wait for all of us to be uploaded now we have basically the same content running on SharePoint online, as you can see from on the address bar. It's also pretty quick.

B

uh So let's go back here, let's just clear that and now I want to add some content to our documentation.

B

So we go back to uh articles and let's go to index. Let's remove that now uh there is the the functions they are inside. This script, I've already imported them. So all I need to do to add something is to say: uh let's uh add an image.

B

So I want a new Doc effects, image link. It says no new images found, but what it did is it created a uh image index file which basically is just a text file that stores all the images that are there and now I copied this little raccoon image to attachments. Folder I'll run that again now, I have now I have the uh a markdown compatible image link part in my clipboard and Link just paste it uh into my uh file and I also want to do some other stuff at.

B

Rpmp demo, which will create a note- and it also includes another file which is uh located here, so that's what I meant what I said. We can reuse content across site because we can just use this include part. uh Now, let's go back to uh the build documents for SPO script.

B

What this also does, is it renames the the last build photo folder to site loss, build and then generates a new one and it compares the file hashes so that it knows which files have changed and it only uploads the changed files to sharepoints. So we don't need to upload the whole site every time which makes it just much more efficient.

B

Now we can see which class has changed and which files are new. So if you go search for new, we can see where two and jpeg is new, and if you go back to our SharePoint site, we should refresh that and we can see the raccoon is here, and you can also see the other content um that uh was read from the other file.

B

Yeah and everything is working so search as well.

B

Everything is searchable within SharePoint, so everything is working as if this web page was running on any other server.

B

So very quick recap: if you want to get started with this first, you need to Define your categories in a CSV file. Then you need to run the initialize dockfx project and to lay out the folder structure, write your documentation, content and then review the content by previewing and verifying the site locally, and then you can publish it to SharePoint or a web server, and this is my contact card, so I'm very active on Twitter, LinkedIn, uh I blog on medium and, of course, I provide the code I write on on GitHub.

B

So that's it from me and back to you, David.

A

Awesome stuff again Martin very, very cool I love how quickly you're able to show implementing and the benefits as well within uh using it in SharePoint doc effects. So really really great job I'm. Sure, there's gonna be lots of collaborative uh questions for you, foreign.