Markdown as the end result with nesting

[kitforbes]

Hello,

We have started using DocFx to generate Markdown files from our assemblies (using DLLs due to a mixture of F# and C#) which we publish on a GitBook site (using GitBook's SaaS approach).

I've been looking through past issues and discussions to figure out the best way to achieve what we are after, but haven't found anything definitive as of yet. Here are the requirements that we have due to the fact that we are using GitBook:

1. Rather than having a flat file (Acme.Plugins.Tasks.EndOfDayTask.md) we want a nested structure for better readability (Acme/Plugins/Tasks/EndOfDayTask.md)
2. Page to page links need to take the nested structure into account ([Acme.Plugins.Tasks.EndOfDayTask](Acme/Plugins/Tasks/EndOfDayTask.md)) and be relative to other pages ([Acme.Plugins.Tasks.EndOfDayTask](../Tasks/EndOfDayTask.md))
3. xref elements are not rendered at all on GitBook it seems, leading to confusing documentation for the reader

So far, I have put together a PowerShell script to handle 1 and 2, and I just need to solve the xref problem in 3. My script is getting quite complicated, making me rethink my process, which is currently:

1. Generate Markdown output with docfx metadata docfx.json to create the flat file structure
2. Create the nested structure by splitting on .
3. Iterate through each document to calculate the relative path to all other documents (a horribly slow process) and modify the links
4. Write a custom Markdown table of contents matching GitBook's approach

I appreciate that the Markdown output is intended as an intermediate step before docfx build, and is currently "beta". So I just wanted to get some opinions from the community on how I could do this better. Should I:

1. Create a post-processor in an attempt to rewrite the HTML files from docfx build as Markdown
2. Modify the docfx source with a new outputFormat of markdownFinal to try and meet my requirements earlier in the process
3. Or, something even better that I haven't considered

Any guidance or feedback would be appreciated!

[kitforbes]

I have worked around my issue with the xref elements with some regular expressions, but I'd still love to hear what people think could work as a nicer way to handle this and similar scenarios.