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, Layout, layout or LAYOUT are exactly the same parameter.

MIIS: parameter prefix: any parameter or field defined in a web.config file 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 web.config.

Out-of-the-box predefined parameters

- TemplatesBasePath

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 ~/Templates.

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.config files. If you set it in a file's Front Matter it will be ignored for the current purpose.

---

- TemplateName

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. You can set it in your web.config file to be applied to the whole folder or application, or in the Front-Matter of files to change it for that specific file only.

If this this parameter is not established or if it's set as none, then a basic minimum HTML5 template is used. See: Serving plain HTML from Markdown. You can specify raw too as the value for this parameter to obtain the raw transformed HTML for the file, without any other "wrapping" tags. This is useful to get raw data from a file, after being transformed and rendered (you can use a .mdh file without any HTML in it to return any kind of data in text format).

---

- Layout

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.

There are several templates included by default with MIIS, and you can create your own from scratch or to retrofit any existing website.

---

- MIME

The normal MIME type to be used in any file is "text/html" since this is what is returned from most of the pages. However you can change it at your own peril using this (Front-Matter only) parameter.

For example, if you want to return a text file from a .mdh file that has enabled TemplateName: raw and therefore will return it's raw transformed contents, you can set up mime: text/plain in the Front-Matter of the file.

If the MIME type is not valid you'll get an error. The MIME type should be registered in IIS in order for it to work. If this is not the case you won't able to get the file from the server.

---

- UseMDCaching

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 web.config file:

<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.config files, and can disable caching for entire sub-folders (for example, one with thousands of files non frequently accessed), or the application as a whole.

---

- UseEmoji

By default MIIS will render standard Emoji codes like the ones used in Github, Trello, Slack, Basecamp and other software. So, strings like :smile: or :grin: are rendered as the corresponding emojis: 😄 - 😁.

You can turn this feature off if needed using this parameter:

<add key="MIIS:UseEmoji" value="1" />

---

- Published

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 false, no o 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.

---

- HttpStatusCode

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:

HttpStatusCode: 404

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).