In my opinion one of the best things about GitHub is the readme.md files (I know, documentation being good, how sad am I). But there is a good reason I like it, documentation is a pain, so having something as simple as a blank markdown file is music to my ears, and storing it with the code, hallaluha.
So it always surprised me Microsoft didn't include a way to add documentation to a Power Platform Solution. Its pretty much perfect for Citizen Developers, who lets be honest don't want to do documentation, so it needs to be:
- Simple
- Quick
- Available
- Stored somewhere easy to find
ago, a readme file in the solution.
But what if I told you there was a readme file in a solution, well a creative workaround, that not only opens up the door for readme files, but possibly more 😎
Web Resources
If you build lots of Model Driven apps, or are just plane nosey, you may have seen Web Resources in a solution.
You normally see them as icons in your model driven apps, and they are designed, as you may have guessed, to add standard web resources to your model driven app to add a bit of customisation.
Whats really cool though is its not just images like PNG's and SVG's, but the full web 3 stack of HTML, JavaScript, CSS. So you can add your custom styles and scripts to your Model Driven apps and embed HTML as a frameset within your page. As you can imagine this was before Canvas pages being available, along with the need for some pro-code knowledge, you see less and less of them being used, but they are still there.
All you need to do is create a new Web Resource in your solution and either paste in the code or select a file to upload (which is best as it auto sets type/name/etc.
But how is resources for Model Driven apps useful for a readme, well it turns out that the files are just hosted within the environment, meaning you can open them by entering the right url (found as a preview link at the bottom of the details pane).
https://{environmentName}.crm.dynamics.com/WebResources/{solutionPrefix}_{name} Call out, the link only works if the resource is published, else its the last version, but the preview link always shows what's uploaded
Yep that's right if you create a HTML Web Resource you can load it directly in your browser (its still behind auth so nice and secure and you need the Basic User security role in the environment to view all of them).
Which is super cool for our readme file, but does give a headache for our Platform Admins. As now any of your developers can deploy a website, it can reference JavaScript from another Web Resource, or use a library site like https://cdn.jsdelivr.net. There are no connections or permissions granted so there is some good news, but it doesn't stop potential malicious code running on a site that your users will trust.
So in a nutshell you should be running checks on Web Resources created in your Default and dev environments, either straight on deleting them or doing some sort of code scans.
How To Create a Readme file
Creating documentation in HTML is just painful, and that's why Markdown was created. Its a cool shorthand version of HTML that is designed to be used when writing content. Most blogging sites use it (including this site), and you may have seen it within the Power Platform when writing to systems like Teams.
The syntax is easy to pick up, I recommend using this cheat sheet when starting out.
The next question is how do we get readme file written in Markdown to load as HTML, luckily there are some cool opensource libraries you can use.
The one I recommend is Markdown-Tag, as its the most easiest and doesn't even need JavaScript to trigger the conversion.
All you need to do is have a simple HTML template file that includes <github-md></github-md> tags containing your Markdown, and a <script> src with markdown-tag-GitHub.js.
Callout here im using a https://cdn.jsdelivr.net to demo, but I would just download the file and host is as its own Web Resource file
And as its standard web 3, you can do other cool stuff, my particular favourite is Mermaid.js. Mermaid converts a simple syntax into a visual diagram.
You need to add to the HTML template <div class="mermaid"></div> tags containing your mermaid code, and a <script> src with mermaid.min.js.
Template
I've created a simple template that just requires the developer to add information per flow in the solution, but you could easily create one for Power Apps/Copilot Studio.
<!DOCTYPE html> <html lang="en"> <head> <title>ReadMe</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <github-md> # Power Automate Flow Documentation ## Overview --- ## Triggers --- ## Connections | Connection Name | API Name | Logical Name | |-----------------|----------|--------------| | | | | --- ## Actions --- ## Variables <div class="mermaid"> </div> </github-md> <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"> mermaid.initialize({startOnLoad: true}); </script> <script src="https://cdn.jsdelivr.net/gh/MarketingPipeline/Markdown-Tag/markdown-tag-GitHub.js"></script> </body> </html> You can check out an example here
But you can either create your own, or if you want some AI magic get Copilot to do it for you (you need the flow definition, which can be found in the workflows/processes table or using my free Chrome/Edge extension AutoReview.
For Power Apps I have create a wen app called AppReview Pro that extracts all the key information and allows you to copy/paste as Markdown (sadly you have to pay for it but there is a 2 week free trial).
And that's it, you now have your very own documentation stored with every solution, and best of all it follows the tried and trotten ReadMe.md approach pioneered by GitHub.
A copy of a working version can be found in the readme solution on my GitHub Repo: https://github.com/wyattdave/Power-Platform/tree/main/Misc%20Artifacts
Top comments (0)