Configuration settings and behavior for MIIS
MIIS needs some basic parameters to be set in order to work. You can set any parameter globally, through
web.config files, or locally in any file through it's Front Matter.
Configuration in MIIS is hierarchical in three levels: root folder, subfolders and pages.
This means that you can define your global parameters in the root folder's
web.config file, define new parameters or overwrite the global ones in any sublevel through the corresponding
web.config inside any sub-folder, and you can define or overwrite any parameter at the page level using the file's Front Matter.
This hierarchical configuration system is very powerful and you can use it to define custom content, to change the navigation system, to choose the template used to render contents in specific sub-folders or files... or even to fully customize any file with specific fields or parameters.
There are some pre-defined parameters in MIIS, and you can create your own custom fields.
Parameter and field names are case insensitive. So,
LAYOUTare exactly the same parameter.
MIIS:parameter prefix: any parameter or field defined in a
web.configfile can be named with a
MIIS:prefix. This helps to avoid conflicts with parameters with the same name from other software you may be using. Using this prefix is optional, but recommended. It'll take precedence over the non-prefixed parameters with the same name in case of conflict. You can't use this prefix in your file's Front Matter. Your file's Front Matter always takes precedence over other parameters or fields defined in
Out-of-the-box predefined parameters
This parameter is only available through
Web.config, and can't be overwritten in a file's Front Matter. It defines the folder that contains the definition for the different templates available to MIIS for rendering pages.
It's default value is
This means that, by default, the templates are located inside a folder named "Templates" in the applications root directory. Normally you won't change this parameter at all.
Note: This parameter can be only set in
web.configfiles. If you set it in a file's Front Matter it will be ignored for the current purpose.
This is the name of the subfolder in the previous
TemplatesBasePath folder, that contains the layout files and the rest of resources for the template we want to use in our site.
If this this parameter is not established, then a basic minimum HTML5 template is used. See: Serving plain HTML from Markdown
The name of the file (including extension) in the previous folder that contains the HTML that defines the current layout to render file contents.
This parameter allows you to point to an HTML file (or any other text file with HTML inside) that will be used to merge it's HTML with the HTML generated from the Markdown files or with the HTML inside the MDH files.
By default MIIS caches the results of rendering any page so that they can render instantly after the first request (no conversion, parameter substitution or processing in every request).
If the file (or any of the files it depends on, such as menus, fragments...) changes, then the cache is automatically invalidated so that the new version is read again from disk in the next request.
If for any reason you need to turn off this behavior (very low memory environments) just use this in your
<add key="MIIS:UseMDCaching" value ="0"/>
This parameters is global and cannot be set individually in the Front-Matter of a single file. You can set it only in
web.configfiles, and can disable caching for entire sub-folders (for example, one with thousands of files non frequently accessed), or the application as a whole.
By default you can't download Markdown files from the server (the source of your final pages). But sometimes it can be useful to allow your users to download the original Markdown files, to use them directly, or to create new versions, etc...
You can switch this feature on through this parameter:
<add key="MIIS:allowDownloading" value="1"/>
After that, any Markdown file registered in your app can be downloaded just adding the
?download=1 query string parameter in the file request.
You can see this feature in practice if you enable this feature and use the provided "Barebones" template, that includes a link to download Markdown files in the footer of every document.
IMPORTANT: in order for the Markdown files to be downloaded you need to add the corresponding MIME type to your web server. CHeck out how to do it.
By default MIIS will render standard Emoji codes like the ones used in Github, Trello, Slack, Basecamp and other software. So, strings like
:grin: are rendered as the corresponding emojis: 😄 - 😁.
You can turn this feature off if needed using this parameter:
<add key="MIIS:UseEmoji" value="1" />
By default all the Markdown and MDH files are published. You can prevent any file or set of files to be rendered by using this parameter.
You can include this parameter in the Front Matter of a file to prevent it to be rendered:
--- Title: My draft page Published: false ---
If anyone writes the path to this file in the browser they will get a 404 Status error of "File not found".
Any value different to
0 will be considered as valid to publish the file. The default value if the parameter is not defined is
true and will render the page normally.
You can set this parameter globally or for specific folders using
web.config and adding:
<add key="MIIS:Published" value="0" />
(any of the previously specified values are valid)
Doing this will prevent the rendering of any file in the folder where this
web.config is located, except those ones that specifically define
Published: true or a similar value in their Front Matter. This can be very useful under some circumstances.
By default all pages return a 200 HTTP Status code, that is: a success code. However, some of the pages that you need in a site must return different status codes to tell browsers and search engines that, for example, a file hasn't be found (404), a file used to exists but no anymore (410) or that a server error has happened (500), among others.
For example, if you're creating a page named
404error.md in the root folder of your site, in order to associate it with the 404 status code so that it's going to be shown when users request a non-existent resource, you should decorate it's FrontMatter with this field, like this:
this will send a 404 status code to the client when a file hasn't been found.
In order for this to work you should assign this file as the one used to handle 404 errors in your site. For this you need to add this nodes to your
web.config file in the root folder:
<system.webServer> <httpErrors errorMode="Custom"> <remove statusCode="404"/> <error statusCode="404" path="/404error.mdh" responseMode="ExecuteURL" /> </httpErrors> </system.webServer>
Now, when a user or a search engine spider asks for a non-existent resource in your site they'll see this page and, what's more important, they'll see the 404 status in the response.
You cannot set the message or other headers sent with this response. For example, status code 301 (permanent redirection) means that a resource has permanently moved and you should indicate in a header the new location of the resource. Since this is something already easy to do directly with IIS/Azure and it's better and more performant to do it that way, this feature is designed only for another types of status code, such as the ones indicated above (404, 403, 500...), which are needed for specific cases and don't rely on extra info sent to the client.
Standard and Custom Fields
There are some basic standard fields that you can use anywhere in your contents or templates.
And most of the provided content templates offer their own parameters to customize a little more the final look and feel
Finally, you can easily define your own custom fields too, and use them anywhere (templates or documents).