Documentor is extremly light and easy to use flat file CMS on .NET 7 for build software documentation.
Inspiration was found in flat file CMS on PHP - Grav. Of course, Grav has more functions in comparison with Documentor, but at the same time Documentor holds all essential functions to quickly and simply create a platform for your software documentation using .NET stack.
It’s used Markdown for documentation description.
- It’s used Markdig for conversion from Markdown to Html. But if you prefer another converter, you can easily use your own implementation of
IMarkdownConverter; - For logging it’s used NLog;
- For generating breadcrumbs it's used SmartBreadcrumbs;
- For building dump it's used SharpZipLib;
- Bootstrap 4, CSS3, HTML5, BEM used to build frontend.
It’s recommended to use XDocumentor for automatic documents generation in Markdown format from Xml-comments in your *.dll.
- Authorization by external resources;
- Documentation pages management includes wysiwyg editor for markdown;
- SEO management;
- Export dump of documentation;
Download last release and open solution. Publish application to target site directory.
Documentor uses authorization on basis of OAuth 2.0 and available emails list. By default next resources are available:
- Google;
- GitHub;
- Yandex;
- Vkontakte.
In file appsettings.json in Authorization.Emails section it's necessary to type emails, which can be authorized in application. It's necessary to type at least one email to start work. You can open access for other users via application interface. Authorized users can use all just listed features. If you create documentation structure and text by hand, authorization is optional.
In site root directory create a subdirectory /Pages, in which one it’s necessary to create a tree of directory with docs.md(required) и metadata.json(optional) files, which will show hierarchy of pages in your documentation.
Example:
Directories must be sequence numbered, as in the example, for correct order display in navigation.
docs.md(required) - file in Markdown format with documentation text;metadata.json(optional) - file in JSON format with metadata for documentation pages.
Example fo metadata.json:
{
"Title": "Start page",
"Description": "Let's start this documentation"
}Fields description in metadata.json file:
| Name | Description |
|---|---|
| Title | Page title, which displays in nav and in title meta tag |
| Description | Page description, which displays in description meta tag |
For configuration it’s used appsettings.json file. Description of main fields from App section is in appsettings.json file:
| Name | Description |
|---|---|
| DisplayName | Your software name, which will be displayed in site header. (default: 'Documentor') |
| ShowSequenceNumbers | To display or not to display sequence numbers in navigation. (default: true) |
| Download.Url | Direct reference to download your software last version |
| Download.Version | Your software last version number |
| ExternalLinks | Links to package managers |
Description of main fields from IO section in appsettings.json file:
| Name | Description |
|---|---|
| Pages.Path | Path relative to site root, where documentation structure is placed (default: 'Pages') |
| Cache.Path | Path relative to site root, where cache for documentation and navigation pages is placed. (default: 'Cache') |
| Cache.Expire | Time in seconds, over which cache for documentation pages and navigation will be updated (default: 604800s = 7 days) |
Documentor is Copyright © 2018 Alexey Drapash, Creacode under the MIT license.