Markdown documentation in Visual Studio Solution

Question

I started a new project using c# and Visual Studio 2017. My goal is to manage the documentation inside Visual Studio to have all files in one place and a complete and easy accessable history in TFS/Git.
I have the code in the src folder, the test projects in the test folder, the documentation as Markdown files in the docs folder (I use Markdown Editor). There is also a Readme.md in the root folder:

Now there are some problems:

• The structure in Visual Studio is different than in the file system. All md-Files I create in Visual Studio are placed in the root directory of the Solution. I could create the files in Windows Explorer and add "Existing Item" but this is a pain.
• I can move md-files in Visual Studio but they won't move in the file system.
• All file references are saved in the sln-file which would change a lot. I'd like to avoid that.

I read about creating an empty c# project and disable building for that project but that seems like a hack too.

Are there some recommendations to manage documentation files in Visual Studio?

Answer 1

As in this answer, it is possible to use the linked file feature in Visual Studio 2017 to link an entire directory, provided you are using the new .csproj project format and you have the .NET Core 2.0 SDK installed in addition to Visual Studio 2017 15.3+.

<EmbeddedResource Include="..\..\..\docs\**\*.md" LinkBase="docs" />

This will link a docs subfolder using the relative path of your project to a folder within the project named docs (the LinkBase). Every time you add, remove, or change a file in the docs folder or nested folder, the changes will be recognized by Visual Studio (it may prompt you to update the file in Visual Studio if it is already open).

Note that you can use this feature on other MSBuild Project Items besides EmbeddedResource as well, such as Content, Compile, or None.

Projects

Technically, Visual Studio solution files are projects. You can see this by opening the .sln file in a text editor:

Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{4016BDAB-6C33-4D1E-9439-57B416EA45D5}"
    ProjectSection(SolutionItems) = preProject
        build.bat = build.bat
        build\build.ps1 = build\build.ps1
        src\CommonAssemblyInfo.cs = src\CommonAssemblyInfo.cs
        TestTargetFramework.proj = TestTargetFramework.proj
        Version.proj = Version.proj
    EndProjectSection
EndProject

Unfortunately, the .sln format doesn't provide many options. As you can see in Hack the Project and Solution Files, the ProjectSection simply lists the dependencies of the project, and optionally has the ability to specify a "real" relative file path. But that is pretty much it. And according to this similar question, it is not possible to link a directory to another directory in a .sln file.

The only difference between the above Solution Items "Project" and a .csproj project is that the latter shifts control of where the files are added to the .csproj (MSBuild) file.

Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MyProject", 
"src\MyProject\MyProject.csproj", "{3A0AA37E-2B7B-4416-B528-DA4E0E6A6706}"
EndProject

However, as the this answer points out, another workaround is to add a Web Site Project, which will add a project with no .csproj file that keeps track of files on disk "in real time", similar to how the new .csproj format works in Visual Studio 2017.