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?

I have a question about managing livestock using Gimp... I'd like to put pictures of all my cows inside layers in Gimp without actually saving them in the .xcf file — Nyerguds, Feb 03 '18 at 17:20
@Nyerguds Thank you for your comment. Unfortunately I don't get what you want to tell me. Is this a question? — Sammy Berg, Feb 03 '18 at 17:51
I'm wondering if you are using the correct tool for this job. You know source control services like Git can perfectly be used on bare folders, right? You don't need a solution file for that. And, the project file is your project's file table. Of course a file can't exist in the project without being referenced in there; it's what the file _does_. — Nyerguds, Feb 03 '18 at 17:53
That said, I have never heard of the solution's tree being different from the file tree. Are you sure you are using the Solution Explorer, and not the Class View? — Nyerguds, Feb 03 '18 at 17:56
I know Visual Studio is no documentation tool but everything I need is available. Just some things are annoying but still better than editing the files with a different tool. — Sammy Berg, Feb 03 '18 at 20:18
Solution folders are not created in the file system. Folders in projects are created in the file system but I try not to use a .csproj or something like that. — Sammy Berg, Feb 03 '18 at 20:24
Then... doesn't simply "making a project inside the solution and putting everything in there" solve all your issues? afaik that's the way solutions are meant to be used anyway. — Nyerguds, Feb 03 '18 at 20:24

NightOwl888 · Accepted Answer · 2018-02-03T20:57:35.673

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.

Thank you but I'd like to add the files directly in the solution without using a .csproj file. — Sammy Berg, Feb 03 '18 at 20:29
See my edit. Solution Files *are* projects, just of a different type. — NightOwl888, Feb 03 '18 at 20:58
Thanks, that was what I was looking for. I now added an "ASP.NET Empty Web Site" project and deleted all containing files which eventually is an empty folder without "Properties" and "References". — Sammy Berg, Feb 03 '18 at 21:40

Markdown documentation in Visual Studio Solution

1 Answers1

Projects