Preprocessing Markdown Documents for Keywords

Question

I recently added a feature to my application to serve arbitrary markdown documents from a directory. This is designed to allow authors to populate a folder full of help documents, and be able to view them without any code changes. However, because this is an MVC application, I needed a few extra features. Straight to it, here's my controller:

public class DocumentationController : Controller
{
    private const string DefaultDocPage = "Overview";
    public ActionResult Index(string id = null)
    {
        ViewBag.HomeLinkPage = string.IsNullOrEmpty(id) || id == DefaultDocPage ? string.Empty : DefaultDocPage;
        if (string.IsNullOrEmpty(ViewBag.HomeLinkPage))
        {
            id = DefaultDocPage;
        }
        var filePath = Server.MapPath(Url.Content("~/Content/Documentation/" + id.Trim("/".ToCharArray()) + ".md"));
        if(!System.IO.File.Exists(filePath))
        {
            Response.StatusCode = (int)HttpStatusCode.NotFound;
            return null;
        }
        var contents = new StringBuilder(System.IO.File.ReadAllText(filePath));

        contents.Replace("{{AppRoot}}/", Url.Content("~"));
        contents.Replace("{{Documentation}}", Url.Content("~/Documentation"));
        contents.Replace("{{DocumentationImages}}", Url.Content("~/Content/Documentation/images"));
        contents.Replace("{{SupportLink}}", ConfigurationManager.AppSettings["SupportLink"]);
        return View("Index", (object)contents.ToString());
    }
}

In short, it allows passing a file name (without ".md") called "id" (poor name is my fault for lazy routing), assigns a default document if a file name was not passed, sets a ViewBag link to the homepage if we're not on the default document, maps the file name to a markdown document in the directory, replaces some preprocessed keywords, and returns the view with the contents of the document.

My view renders the homepage link, if applicable, then the document using MarkdownSharp. I haven't seen my idea of "preprocessed keywords" in markdown before, so I was wandering what others think. It's really useful for resolving links in documents, without worrying about them while writing. It allows document writers to write:

To view your user page [click here]({{AppRoot}}/User/Me) and here's an image: ![image]({{DocumentationImages}}/UserPageImage.png)

Which is transformed to this, on localhost, without the author worrying about the actual path to the application, or the content directory:

To view your user page [click here](http://localhost/MyApp/User/Me) and here's an image: ![image](http://localhost/MyApp/Content/Documentation/images/UserPageImage.png)

I also added one for the support link, so I could pull in that setting from ConfigurationManager.AppSettings.

My questions, succinctly:

• Are there any realistic cases that I may not be anticipating?
• Is there a best practice that I'm not aware of, for having pre-processed text replaced in markdown?
• Is there a better way than StringBuilder.Replace for processing each of my keywords?

Answer 1

A few minor nit-picks:

1. I'd change the id checking code around a bit to avoid some redundant checks by first sanitizing the input:

   id = string.IsNullOrEmpty(id) ? DefaultDocPage : id;
   ViewBag.HomeLinkPage = id == DefaultDocPage ? string.Empty : DefaultDocPage;
   

2. Consider making DefaultDocPage a configurable property so you don't have to change the code if when someone asks to have a different name

3. Trim takes a params array so there is no need to do the ToCharArray, you can just pass in all the trim characters directly like this:

   id.Trim('/')
   

4. Replacing

   var filePath = Server.MapPath(Url.Content("~/Content/Documentation/" + id.Trim("/".ToCharArray()) + ".md"));
   

   with string.format makes it a bit easier to read:

   var filePath = Server.MapPath(Url.Content(string.format("~/Content/Documentation/{0}.md", id.Trim('/'))));
   

1. There is no need to cast to object here:

return View("Index", (object)contents.ToString());