docFX generating inconsistent line terminators in .html files (some LF, some CR LF)

[FrizzSoft]

I am new to DocFX, but getting to understand it. I recently went to “git commit” my project (with docFX docs in /docs folder) and received multiple warnings like this:

warning: in the working copy of 'docs/api/index.html', LF will be replaced by CRLF the next time Git touches it

I received the same warning for the majority of files generated by docFX.
I believe I have determined the reason for these warnings. On investigation, the warning is generated because I am working on a Windows machine where the default line terminator is a CRLF pair. I have git configured with:

git config --global core.autocrlf true

which is the appropriate setting when working on a Windows machine. It results in git converting line terminators in text files from CRLF -> LF when committing, then converting back from LF -> CRLF when restoring to your working tree. The warning arises because git detects some LF (only) line terminators in the docFX-generated documents, and is warning you that if you restore from a commit these documents will be altered to CRLF.

I know this is not a ground-breaking issue and won’t affect the functionality of the document website. However, the warnings are disturbing and make you wonder if you are doing something wrong. It certainly led me to waste a lot of time determining the cause. On further investigation I noted that the .html files implicated had the majority of their lines correctly terminating with CRLF, but any lines ending in a </p> or </ul> closing tag, or lines where multi-line text strings wrapped to the next line, each were terminated with LF only. This was causing the warnings. I believe this may be a bug in docFX.

Can anyone caste further light on this for me. Thanks in advance.
David

[filzrev]

For temporary workaround.
It can be resolved by changing docfx HTML template file's line separator from CRLF to LF.
I've confirmed it can be fixed by executing following PowerShell script.

$ErrorActionPreference = 'Stop'
cd $env:UserProfile\.dotnet\tools\.store\docfx\2.70.4\docfx\2.70.4\templates

$paths = @(
 '*.tmpl',
 '*.tmpl.partial'
 '*.html.primary.tmpl',
 '*.html.tmpl' 
)

foreach($path in $paths){
  Get-ChildItem -Recurse -File -Path $path | foreach {
    ((Get-Content $_.FullName -Raw -Encoding UTF8) -replace "`r`n","`n") | Set-Content $_.FullName -Encoding UTF8
  }
}

---

I thought there are following problems in current docfx implementation that cause output HTML contains mixed CRLF/LF.

1. docfx template files are using CRLF as line separator.
   And outputted HTML always use CRLF regardless of execution environment.
2. Markdig use LF char by default. (It need to call ConfigureNewLine(Environment.NewLine) to change this behavior)

I though it's undesirable behaviors that output HTML file contains both LF/CRLF.
So it's better to use only LF or normalize HTML in HtmlPostProcessor.

[FrizzSoft]

Thanks for the feedback. I'm not going to worry about the temporary fix as the problem only results in git warnings.
But do you think it is worth creating an issue from this discussion? It would be best to fix it at the source.

[filzrev]

Latest docfx version (v2.71.1) changes HTML templates line separator to LF.
So mixed CRLF/LF problems are resolved when using latest docfx.