-
Notifications
You must be signed in to change notification settings - Fork 884
-
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:
- Rather than having a flat file (
Acme.Plugins.Tasks.EndOfDayTask.md) we want a nested structure for better readability (Acme/Plugins/Tasks/EndOfDayTask.md) - 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)) xrefelements 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:
- Generate Markdown output with
docfx metadata docfx.jsonto create the flat file structure - Create the nested structure by splitting on
. - Iterate through each document to calculate the relative path to all other documents (a horribly slow process) and modify the links
- 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:
- Create a post-processor in an attempt to rewrite the HTML files from
docfx buildas Markdown - Modify the
docfxsource with a newoutputFormatofmarkdownFinalto try and meet my requirements earlier in the process - Or, something even better that I haven't considered
Any guidance or feedback would be appreciated!
Beta Was this translation helpful? Give feedback.
All reactions
Replies: 1 comment 2 replies
-
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.
Beta Was this translation helpful? Give feedback.
All reactions
-
Hi @kitforbes, can you share your work around script?
Beta Was this translation helpful? Give feedback.
All reactions
-
I rewrote everything as a C# application to make it all more manageable. Digging through the Git history, looks like I was handling the xref like this:
$result = $result -replace '<xref href="(.*?)" data-throw-if-not-resolved="false"><\/xref>', "```${1}``"
This comes from a PowerShell function I wrote which expects Content to be a Markdown file generated by Docfx.
function ConvertFrom-HtmlToMarkdown { param ([String]$Content) $result = $Content # We use the "Replace()" function here so that the "Singleline" option can be used. $result = [Regex]::Replace($result, '<span class="term">(.*?)<\/span>', '${1}', [Text.RegularExpressions.RegexOptions]::Singleline) # Replace HTML elements with Markdown syntax. $result = $result ` -replace '<a id=".*?"><\/a> ' ` -replace '<xref href="(.*?)" data-throw-if-not-resolved="false"><\/xref>', "```${1}``" ` -replace '<ul>' -replace '</ul>' ` -replace '<li>', "`n* " -replace '</li>' ` -replace '<p>', "`n`n" -replace '</p>' ` -replace '<b>', '**' -replace '</b>', '**' ` -replace '[\s-[\r\n]]+$' # Replace some URL encoded characters. $result = $result ` -replace '%5b', '[' -replace '%5d', ']' ` -replace '%7b', '{' -replace '%7d', '}' ` -replace '%2c', ', ' -replace '%60', '\`' # Other clean-up specific to Docfx. $result = $result -replace '[\r\n] \[', "`n[" return $result }
Beta Was this translation helpful? Give feedback.
All reactions
-
❤️ 1