[DocFx] Create articles

 DocFx   Articles  

▌Introduction

---

We will learn how to write articles in markdown with DocFx.

In this tutorial, we use the same DocFx website in previous article:

[DocFx] Create api documents on multiple projects

▋Related articles

1.  [DocFx] Create api documents on multiple projects

2.  [DocFx] Create articles

▌Environment

---

▋Visual Studio 2017 community

▋docfx.console 2.38.1

▌Implement

---

▋Write markdown article

The articles(markdown file) should be put in ./articles in default.

I created

./articles/ngrx/README.md

./articles/ngrx/assets/

The content of README.md is as following,


- [[Angular] Redux with ngrx/store – Intro](http://karatejb.blogspot.tw/2017/01/angular2-redux-with-ngrxstore-intro.html)

- [[Angular] Redux with ngrx/store – Shopping cart sample (1)](http://karatejb.blogspot.tw/2017/01/angular2-redux-with-ngrxstore-shopping.html)

- [[Angular] Redux with ngrx/store – Shopping cart sample (2)](http://karatejb.blogspot.tw/2017/01/angular2-redux-with-ngrxstore-shopping_10.html)

- [[Angular] Redux with ngrx/effects – Shopping cart sample (3)](http://karatejb.blogspot.tw/2017/03/angular-redux-with-ngrxeffects-shopping.html)

▋Update TOC(Table Of Content) file

Open ./articles/toc.md

We append the title of our new article and set the relative path.

#[Introduction](intro.md)

#Angular

##[ngrx tutorials](ngrx/README.md)

Which will create TOC like this,

▋Preview result

Now build the project and start the website, you will find that the HTMLs are created automatically by DocFx.

Notice that the assets folder won’t be copied to _site/articles/ngrx/, so when you browse the article, the images cannot be shown as below.

▋Add redirect rules (Only works when running on IIS)

Since we are using DocFx in a website, add the following redirect rule in WebConfig to make the image working. Of course it will not work when you serve the website with DocFx command-line tool!

<system.webServer>

    <rewrite>

      <rules>

        <rule name="AssetRedirect" stopProcessing="true">

          <match url="^_site/articles/(.*)/assets/(.*)" />

          <action type="Redirect" redirectType="Permanent" url="articles/{R:1}/assets/{R:2}" />

        </rule>

      </rules>

    </rewrite>

</system.webServer>

Here you can also solve the inconvenient url issue, add the following redirect rule to redirect http://localhost:<port> to http://localhost:<port>/_site

<rule name="RootRedirect" stopProcessing="true">

          <match url="^$" />

          <action type="Redirect" redirectType="Permanent" url="_site" />

        </rule>

Here is the result when you start the website locally by IIS Express.

▋Tip of publish to IIS

The last step publishing to IIS. You can simply use Web Deploy to do it.

Notice that you should include the _site folder into your project(.csproj).

Wait, that means every time we create an article (markdown file), we need to include the output HTML into project to publish it?

Yes, but here is a tip to include the output HTML automatically to our project.

Open MyDocFx.Web.csproj file, add the following settings,

<ItemGroup>

    <Content Include="_site\articles\**\*.html" />

</ItemGroup>

So the output HTML will be included when building the project with DocFx.

▋Demo

▌Reference

---

▋DocFx: Walkthrough Overview