Mater is a simple, open source, GitHub-based doc system built for Microsoft Azure.
We built Mater to manage and publish our documentation and semi-officially announced open-sourcing Mater last week on our Twitter account.
How it works
Mater is designed to store all documentation, images, videos and other assets directly in a GitHub repository.
GitHub provides all of the versioning, change tracking, history, and storage – all in a simple to use interface without requiring a database and the associated web applications for managing all of those assets.
Documentation is written in Markdown, but can also include HTML, and saved in files with the .md extension.
What’s great about this is that it keeps things very simple: documentation is just like any other project resource.
Azure Integration
When a new documentation asset, such an update to a documentation file, is committed to the GitHub repository, it is automatically published to your Azure Web App running Mater.
You can create your own documentation approval workflow through GitHub and let Mater take care of the publishing and user experience.
What about Search?
Mater supports Microsoft Azure Search with a few additional steps.
First, you’ll need an instance of Azure Search. Next, you’ll need to configure some environment variables in your Mater Web App. Finally, you’ll need to run the Mater WebJob to keep your index up to date.
The end result is that all of your documentation is now searchable:
Features
Mater does quite a few things for you beyond formatting and helping organize your documentation:
Custom CSS
Mater is built on Bootstrap, but you can inject your own CSS by including a styles.css file in the root of your documentation repository.
Customer <head> content
You can add anything else you want to the <head> section of the HTML that Mater generates by simply including a head.html file in the root of your documentation repository.
Pages titles, description and more
You can include JSON at the top of any of your documentation files to provide additional information to Mater about your content, e.g. setting custom page titles, descriptions and which view Mater should use to display your content.
Google Sitemap
Mater automatically generates a Google Sitemap that you can submit to Google to ensure all your content is in Google’s search index.
Just add /sitemap to the end of your Mater site:
Json
Mater automatically generates Json versions of all your documentation, including your Sitemap. This is used by the Search WebJob to index your content, but can also be used by your application – such as adding help inline.
To return a Json representation of your content, simply add /json/ prior to the name of the document you want.
What’s on the Roadmap?
Here’s a partial list of things we’re thinking about adding:
- Document read time – a simple estimate of the time required to read the document. Similar to Medium.
- Auto-delete on 404 – specifically to help ensure the search index for your Mater repository automatically removes any content that isn’t found.
- Built-in CSS – we’ve added a few custom CSS rules, such as support for steps, but we’d like to include more.
- Contributors – automatically get a list of contributors from GitHub for the requested document and display that in the documentation.
- Alternative layouts – Mater only supports a single layout right now: table of contents on the left and content on the right. We’d like to include some alternative layouts.
If you would like to contribute or have suggestions, we’d love the feedback.
