- Downgrade the severity of empty input files from
warning
tosuggestion
. (#6206) - Fix style issue of NOTE sections in PDF. Thanks @Blake-Eryx! (#6211, #6271)
- Bug fix:
- Fix updating links unexpectedly when building docs.microsoft.com docset for review purpose.
- Support excluding default TOC in PDF. Thanks @Blake-Eryx! (#6146)
- Improvement and bug fix in code extension. (#6070)
- Bug fix:
- Fix TOC scrolling to wrong place. Thanks @Spongman! (#4470)
- Fix NOTE/WARNING/INFORMATION/CAUTION/TIP sections style. Thanks @Blake-Eryx! (#6082)
- Support setting
wkhtmltopdf.exe
path in CLI option. Thanks @icnocop! (#6040) - Make console output readable under white background. Thanks @paulpach! (#5309)
- Improvement and bug fix in code extension. (#5945, #5968)
- Ensure
SourceBasePath
present in manifest when a version contains no files. (#5960) - Bug fix:
- Fix failing to search for methods by name. Thanks @paulpach! (#5695)
- Supporting setting
wkhtmltopdf.exe
path in config. Thanks @icnocop! (#4422) - Add video Markdown extension syntax. (#5945)
- Bug fix:
- Fix inaccurate error message when UIDs are duplicate. (#5898).
- Bug fix:
- Downgrade error to warning for Markdown complex image.
- Support extracting metadata from FSharp projects incrementally. Thanks @saul! (#5810)
- Support XrefService as parameter. e.g.
docfx --xrefService https://xref.docs.microsoft.com/query?uid={uid}
. (#5786) - Feature, improvement and bug fix in several Markdown extension syntax. (#5792, #5804, #5838, #5857)
- Do not warn when certain output is empty. (#5878)
- Bug fix:
- Fix crash when building FSharp projects with override methods. Thanks @saul! (#5811)
- Fix applying template preprocessor failure for Python reference in some cases. (#5781)
- Fix PDF outline issue, add check for user style sheet existence. Thanks @icnocop (#5490, #5858)
- Improve readibility of default theme (#5156). Thanks @djee-ms!
- Support F# v4.5 language features (#3679). Thanks @smindinvern!
- DocFX returns
-1
for errors that cause notable result missing,1
for crash or severe errors,0
for success. Before, DocFX returns1
when error happens no matter which kind it is. (#5734) - Bug fix:
- Fix TOC filter in statictoc template for Edge and IE browser (#5651). Thanks @Blake-Eryx!
- Support fetching xref map from fallback folder. (#5593)
- Improve error handling to remove some duplicate error logs.
- Improvement and bug fix in code extension.
- Avoid URL encoding allowed URI characters
(
and)
when generating links (#5537). - Ensure more deterministic output (#4569). Thanks fibann!
- More chance to build incrementally when plugin assemblies have only slight change (#5572).
- Bug fix:
- Fix crash when inheritdoc targets non-existent definition (#5561).
- Fix several code extension bugs (#5546).
- Add
cref
attribute support (#1306) for inheritdoc and fix copying from templated sources (#1516). Thanks @amirebrahimi. - Bug fix:
- Fix TOC filter returning unrelated results (#5401). Thanks @zwfars
- Fix duplicate error when TOC is invalid (#5464).
- Fix several code extension bugs (#5510 #5527).
- Bug fix:
- Fix failure building UWP project. (#5011)
- Fix former post processor's metadata changes lost in later post processor. (#5366)
- Support fetching region from referenced XML code snippet in XML documentation comments. (#5319) Thanks @Laniusexcubitor!
- Bug fix:
- Fix NullReferenceExcpetion when input YAML content is empty file. (#5254)
- Add persistence to the TOC filter (#5164). Thanks @jo3w4rd!
- Bug fix:
- Fix StackOverflowExcpetion when resolving cross reference. (#4857)
- Fix parsing
~/
in link path. (#5223)
- Support Jupyter Notebook in code snippet (#4989, #5000). Thanks @pravakarg, @sdgilley!
- Upgrade to Microsoft.CodeAnalysis 3.3.1 for C# 8.0 support (#5163). Thanks @dlech!
- Improve the default template for TypeScript documentation (#5128). Thanks @rbuckton!
- Improve logging of template preprocessor errors (#5099). Thanks @mcm-ham!
- Bug fix:
- fix duplicate warnings when include the same file multiple times. (#5093)
- Improve performance by upgrading Jint to 2.11.58. (#5032)
- Resolve UID from xrefmap respecting the order defined in
docfx.json
. (#5094) - Bug fix:
- Fix incremental build error when previous build has no content. (#5010)
- Fix PDF cover page not work. (#5077)
- Enforce trailing
]
when matching file inclusion Markdown syntax. (#5091)
- Support linking to repository from dev.azure.com automatically. (#4493)
- Unify log code
InvalidInternalBookmark
andInvalidExternalBookmark
intoInvalidBookMark
. - Expand environment variables in metadata/build
src
section when looking for input files. (#4983)
- Bug fix:
- Fix running under Linux/Mono (#4728). Thanks @tibel!
- Fix PDF build failure under Azure DevOps with a new config
noStdin
(#4488). Thanks @oleksabor! - Fix truncation issue in side bar (#3166). Thanks @icnocop!
- Fix a scrolling issue when clicking the same achor twice (#3133). Thanks @icnocop!
-
Support Visual Studio 2019. (#4437)
[Note] This will break running under Linux/Mono. Before it is fixed, you can keep using v2.42.4.
- Drop project.json support. (#4573)
- Bug fix: use remove instead of add to remove duplicate items.
- fix JavaScript error when clicking on "In This Article" links in the side navigation of the default website template. (#4419)
- Revert PDFSharp back to iTextSharp (#4407)
- fix NullReferenceException in dependency command.
- PDF features:
- Added support for a cover page when generating a PDF. (#2004)
- Added the ability to change the default "Cover Page" bookmark for the TOC in the PDF. (#4278)
- Added the ability to specify the type of outline to use when generating a PDF.
- Replaced iTextSharp with PdfSharp (#4250).
- [Breaking change] Removed support for OutlineOption.CustomOutline when generating a PDF.
- Bug fix:
- Prevent adding duplicate HTML files when generating a PDF.
- Performance improvement:
- [Breaking Change] Abandon metadata on resource files, including global/file metadata, and paired
.meta
files. - Fix several performance issues.
- [Breaking Change] Abandon metadata on resource files, including global/file metadata, and paired
- Improve warnings when configuration contains invalid glob pattern in
exclude
section. - Stablize result if multiple TOC links to the same file.
- Bug fix:
- Search bar not showing in
statictoc
template. (#3109) - false invalid bookmark warnings when linking to H1 heading. (#4155)
- Search bar not showing in
- Improve performance in Markdig Markdown engine. (#4048)
- Bug fix:
- DocFX fails when runs under Mono on Linux/MacOS. (#3389 #3746)
- Add new severity level -
Suggestion
.
- Bug fix:
- Non-source files should not be included in file metadata changes when incremental build.
- Fix error extracting metadata from DLL files. (#3979)
- Performance improvement:
- Increase incremental build chance when
fileMetadata
changes. (#3816) - Improvement query performance when extracting metadata. (#3207)
- Increase incremental build chance when
- Fix perf issue when report toc dependency.
- Transform code language extracted from triple slash comments to style class.
- Fix cache corruption when shrink multiple times
- Show warnings on page when codesnippet is not found.
- Bug fix:
- Fix EntityMetadata for FSharp when parsing signature files.
- Fix FSharp tests.
- Bug fix:
- Fix EntityMetadata for FSharp when parsing signature files.
- Bug fix:
- Fix toc ui of static template. (#3606)
- Add cache to fix swagger parser perf issue.
- Add dropdown fix to static toc template. (#3361)
- Fix codesnippet tagname bug.
- Upgrade Markdig to 0.15.4
- Fix ArgumentNullException error when extracting metadata from DLL. (#3374)
- Update Nuget package config.
- Fix Chocolatey package download error. (#3349)
- Support warnings as errors by
--warningsAsErrors true
. (#3229) - Support for value tuples in documentation. (#2512 #3211)
- Upgrade to net462 and support long path. (#3183)
- Upgrade Microsoft.Build to work with VS 15.8. (#3158 #3225 #3231)
- Bug fix:
- Fix yamlheader in inline inclusion (#3203)
- Support
--disableDefaultFilter
to disable default API visibility filter rule. (#2561) - Improve warning message for invalid link in TOC inclusion (#3106)
- Support dropdowns in top navigation bar. (#3168)
- Bug fix:
- Refine regex for tables and add timeout (#3118)
- Defaults to TLS 1.2 when query from xref service and download xref map.
- Bug fix:
- Fix FSharp project loading. (#2960)
- Bug fix:
- Improve download command error message. (#2805)
- Fix code indent issue. (#2830)
- Fix error when generating metadata. (#2852)
- Bug fix:
- Fix .targets file. (#2804)
- Fix missing publish
Microsoft.DocAsCode.Metadata.ManagedReference.FSharp
NuGet package. (#2779)
- Allow setting the base path for code sources. (#2131)
- Bug fix:
- Fix API filter for attribute. (#2451)
- Fix error when attribute has null value. (#2539)
- Fix Markdown when link contains space. (#2681)
- Fix XML comment merge not preserving inheritdoc metadata.
- Fix page error under Internet Explorer 11 (#2741)
- Disable building document when live unit testing.
- Bug fix: Tabbed content always enables second tab. (#2706)
- Bug fix: codesnippet tagname is not recognized when the tag starts with \t in Markdig.
- Bug fix:
- Fix Tabbed Content rendering bug. (#2645)
- Fix script error in getHierarch. (#2624)
- Fix loading csproj NullObjectReferenceException. (#1944)
- Fix affix "active" class issue. (#2658)
- Bug fix:
- Fix error with enum flags in attributes. (#2573)
- Improve syntax formatting when containing
where
keyword. (#2410) - Fix XML syntax highlighting issue. (#2553)
- support more languages for markdig (#2574)
- MonikerRange infinite loop bug (#2572)
- Enable emoji in markdig
- Decode href in FileLinkInfo
- Support generating API reference for TypeScript (#2220)
- Bug fix:
- XRefService lookup of generic classes doesn't work (#2448)
- Fix yaml serialize for string '~' (#2519)
- Fix link bug after
<a/>
in markdown (#2521) - Fix VSTS's git url under detached HEAD (#2516)
- Bug fixes:
- Fix metadata broken with mono and linux (#2358).
- Partially fix metadata broken with latest VS 15.6 with workaround:
set VSINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise set VisualStudioVersion=15.0 set MSBuildExtensionsPath=C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\MSBuild\15.0\Bin
- Support remove special host name from xref service.
- Bug fixes:
- Fix empty code block in markdown(dfm, dfm-latest).
- Upgrade Roslyn's CodeAnalysis assemblies to latest 2.6.1
- Bug fixes:
- Fix bug for missing
seealso
section in enum pages (#2402) - Fix bug for supporting
in
keyword which is introduced in by C# 7.2 (#2385) - Fix runtime error when EII name hits VB preserved keywords (#2379)
- Fix
docfx.console
so that it can support the new netstandard csproj format (#2142)
- Fix bug for missing
- Improve DFM performance for em rule (#2339)
- Support generating API reference for JavaScript (#2220)
- Bug fixes:
- Fix bug for query xref service (#2283)
- Fix toc race condition and improve perf
- Bug fixes:
- Fix issues running under mono (#2262, #1856)
- Fix VS17 15.5 support (#2265)
- Bug fixes:
- Fix .NET core .csproj files support (#1752)
- Add warning throttling. (#2187)
- Enable schema validation for SDP.
- Bug fixes:
- Fix markdown link behavior. (#2181)
- Fix xref map sorted comparer. (#2191)
- Fix yaml deserialize for int64. (#2193)
- Fix xref query filter. (#2195)
- Fix
docfx metadata
failure after VS2017 Update 15.3. (#1969) - Provide
MetadataOutputFolder
MSBuild parameter withdocfx.console
. (#2194)
- Improve code snippet, add cs snippet for cshtml, add vb snippet for vbhtml.
-
New feature:
- Support new syntax in Markdown: tabbed content
# [Csharp](#tab/csharp) ```cs Console.WriteLine("Hello world"); ``` # [JavaScript](#tab/js) ```js console.log('hello world'); ```
Renders to:
Console.WriteLine("Hello world");
console.log('hello world');
-
Fix bugs:
- Update DFM XREF short format.
- Update Markdown EM rule.
- Fix post-processor incremental bug that incremental post-processor is always disabled
- Disable schema validation in schema-driven document processor temporarily.
- Disable loading overwrite documents in schema-driven document processor temporarily.
- Use wbr instead of zero width space
- Remove warning invalid file link when customized href generator can resolve it.
- Support generating sitemap with at least
"sitemap": { "baseUrl": "https://yourwebsite.com/" }
defined in"build"
section ofdocfx.json
(dotnet#1979) - Support responsive table: dotnet#2024
- Bug fixed:
- Multithreads issue for reading xref zip file.
- 404 issue for generated site. dotnet#1858
- Log warning for manage reference yaml file without yaml mime.
- Obsolete external reference. Please use xref instead.
- Add xref query client.
- Upgrade Roslyn's CodeAnalysis assemblies to latest 2.3.1
- Schema-driven document processor related
- support
metadata
keyword - support all the functionalities defined in the spec
- support
- Advanced
xref
syntax support:<xref uid="System.String" template="partials/layout_section.tmpl">
- Support global metadata and file metadata for TOC files
- Add class level implements to default template. dotnet#1223
- Obsolete
version
and usegroup
instead. - Bug fixed:
- Fix #1982: c# 7.1 feature
default
is not correctly handled
- Fix #1982: c# 7.1 feature
- Improve error message for invalid toc yaml file.
- Use xhtml for dfm default setting.
- Add language support for aspx-cs and aspx-vb in code snippet.
- Bug fixed:
- Fix #1825: ArgumentNullException when EII implements a member with EditorBrowsableState.Never.
- Fix #1937: Anchor icon overlays Note icon.
- Fix #1951, #1905: Running DocFX from outside the folder fails
- Fix #1915: Cannot generate docs of two assemblies
- Fix #1900: Add back Microsoft.CodeAnalysis.Csharp.Features.dll dependency
- Support REST extensibility by
rest.tagpage
andrest.operationpage
plugins, to split the original REST API page into smaller pages. Refer to plugins dashboard for more details. - Bug fixed:
- Fix _rel unfound when href is url decoded.
- Fix #1886: Fails when project doesn't contain git remote information.
- Fix toc restruction to support expand child by sequence.
- Ignore default plugged assemblies when loading plugins.
- Add anchor links to default theme.
- Disable LRU cache as it has race condition bug and not easy to fix.
- PDF improvements:
- Intermediate html files are now removed by default, you can use
--keepRawFiles
option to keep them. - Add syntax highlight to PDF, it is using highlight.js in client-side js.
- Add hook files to css and js, you can now customize PDF styles by adding your own
main.css
andmain.js
.
- Intermediate html files are now removed by default, you can use
- Change the default behavior of incremental build that it is always based on the same cache folder (originally the cache folder changes in every build and copy historical files form last cache folder). You can use
--cleanupCacheHistory
option to cleanup the historical cache data. - Bug fixes:
- Fix #1817: Error extracting metadata when containing constant surrogate unicode character.
- Fix #1655: Using hashtag in external cross reference broken.
- Fix #219: Fails when source code contains two type names that differ only in case
- Fix #164: Clean up previous auto-generated metadata YAML files when calling
docfx metadata
- Fix #1797: the command docfx template list does not show the pdf template
- Fix #1803: Overriding example with *content in same file as other overrides doesn't work
- Fix #1807: XREF link to API doc with wildcard UID not getting generated
- Fix #1823: Metadata being generated from referenced projects
- FIx #1824: Change generated .manifest file to be indented and ordered.
- Enable incremental Build by default. You can use option
--force
to force rebuild. - Improve
docfx metadata
error message when error opening solutions or projects using Roslyn. dotnet#1738 - Support more develop language for code snippet Markdown syntax. dotnet#1754
- Downgrade the message level for invalid inline code snippet and invalid block file inclusion from Error to Warning.
- Add LogCode for each file to the manifest file.
- DocFX is NOT dependent on Build Tool 2015 anymore.
- Add line and source file info for invalid cross reference
- Bug fixes:
- Fix html pre element behavior in Markdown, empty lines are now allowed in
<pre>
blocks. - Fix #1747: add app.config redirect binding to docfx to resolve LoaderException for docfx metadata
- Fix #1737: it is now possible to use
> [!warning]
format in triple-slash comments - Fix #1319 that docfx fails to load multiple solutions
- Fix #1720 and #1708 that docfx throws runtime error in Mono
- Fix post processor incremental bug: restore manifest should be case-insensitive
- Fix html pre element behavior in Markdown, empty lines are now allowed in
-
PDF is now supported. Refer to Walkthrough: Generate PDF to get start with generating PDF files.
-
Fix default template performance bug that local search is always used.
- Bug fixes:
- Bug fix for markdown empty link.
- Bug fix for html behaivor in dfm-latest.
- Fix Egde crashes with web worker. dotnet#1414
- Bug fix for default template that inheritance is incorrect.
- Bug fix for extracting metadata from assembly that XML comment is not applied.
- Bug fix for template statictoc.
- Bug fix for fail to init markdown style.
-
Introduce Master page syntax into Template System:
- Mustache:
{{!master('<master_page_name>')}}
- Liquid:
{% master <master_page_name> %}
- Mustache:
-
[Breaking Change] View model for
ManagedReference.html.primary.tmpl
is updated from{item: model}
tomodel
, if you overwritesManagedReference.html.primary.tmpl
in your own template, make sure to re-export the template file. -
Simplify
default
template: now you only need to overwrite _master.tmpl to redesign the layout for the website. -
Frontend improvement
- Long namespace name in TOC will be word-wrapped now
- Bug fix for docfx.js when navbarPath or tocPath is empty.
- Bug fixes:
- Bug fix for Null exception when
<xref href=''/>
exists - Bug fix for
docfx metadata
for assemblies, to exclude null assembly symbols. - Bug fix for toc: When b/toc.md is included by toc.md, invalid link in b/toc.md should be resolved to the path relative to toc.md
- Bug fix for Null exception when
- Support the latest csproj format
<Project Sdk="Microsoft.NET.Sdk">
- The latest csproj introduces in a new property
TargetFrameworks
, docfx does not support it for now. To make docfx work, please specifyTargetFramework
when calling docfx. A sampledocfx.json
would be as follows. Themerge
command is to merge YAML files generated with differentTargetFramework
into one YAML file.
{ "metadata": [ { "src": "*.csproj", "dest": "temp/api/netstandard1.4", "properties": { "TargetFramework": "netstandard1.4" } }, { "src": "*.csproj", "dest": "temp/api/net46", "properties": { "TargetFramework": "net46" } } ], "merge": { "content": [ { "files": "*.yml", "src": "temp/api/netstandard1.4" }, { "files": "*.yml", "src": "temp/api/net46" } ], "fileMetadata": { "platform": { "temp/api/netstandard1.4/*.yml": [ "netstandard1.4" ], "temp/api/net46/*.yml": [ "net46" ] } }, "dest": "api" }, "build": { "content": [ { "files": [ "api/*.yml", "**.md", "**/toc.yml" ] } ], "dest": "_site" } }
- The latest csproj introduces in a new property
- Bug fixes:
- Auto dedent the included code snippet, both when including the whole file and file sections.
- [Breaking Change]For inline inclusion, trim ending white spaces, considering ending white spaces in inline inclusion in most cases are typos.
- Following GitHub markdown behavior changes.
- Bug fixes:
- Fix duplicate project references fail GetCompilationAsync. dotnet#1414
- Breaking Change: Create new type for files in manifest.
- Support working folder for dfm include and code.
- Upgrade YamlDotNet to 4.1.
- Support cross file definition reference for swagger.
- Bug fixes:
- Filter config file is expected in working dir instead of project's dir/src dir.
- Create msbuild workspace with release configuration by default. dotnet#1356
- Bug fixes:
default
template: Do not loadsearch-worker.js
when search is disabled indocfx.js
- C# region support for code snippets broken by #endregion with extra text. dotnet#1200
- Markdown list continue with def.
- Markdown link rule is not allowed in link text.
- Markdown list restore wrong context.
- Metadata
_docfxVersion
can't be overwritten. dotnet#1251 statictoc
template out of sync withdefault
template. dotnet#1256- Fix footer covering sidetoc. dotnet#1222
- Export custom href generator.
- Introduce attribute driven data model to Managed Reference
- Bug fixes:
- Generate overload name/fullname form generic method should not contain method parameter.
- Fix href for markdown link to non-exist files in include files.
- Bug fixes:
- Markdown table content is misplaced if there is empty column in it.
- Markdown include should not share link context.
- Fix rawTitle when article's first line is HTML comment.
- hotfix for wrong file link check message.
- Remove commit id to avoid config hash changed.
- Enable to show derived classes.
- Add log for config hash.
- Breaking Change Using
<span class="xxx">
for languageKeyWord, paramref and typeparamref in generated yml files, instead of using<em>
and<strong>
. Change default template accordingly. - Remove project
Microsoft.DocAsCode.Utility
, move class toMicrosoft.DocAsCode.Common
. - Get documentation's git information with git command instead of
GitSharp
. - REST:
- Support
remarks
to be overwritten. - Support reference in parameters to be overwritten.
- Support DFM syntax in swagger description
- Support
- Bug fixes:
- Fix inherited member's name when xref unresolved.
- Fix missing items in breadcrumb. (dotnet#944)
- Fix generating overload method names from generic method.
- Fix full text search not work in index page.
- Fix the warning that no highlight function defined.
- Fix bug: throw error when md contain wrong path..
- Fix bug: RelativePath.TryParse should not throw error when path contains invalid path characters.
- Improve markdown engine:
- Remove paragraph rule.
- Improve parser performance.
- Report bookmarks in template preprocessor, which is used in URL segment when resolving cross reference.
- Support customizing logo and favicon through metadata. (dotnet#892)
- Refine the warning message of invalid bookmark.
- Improve layout for print. (dotnet#852)
- Remove the usage of
FileModel.LocalPathFromRepoRoot
. This property is markedObsolete
. - Copy
PathUtility
,RelativePath
,StringExtension
andFilePathComparer
from projectMicrosoft.DocAsCode.Utility
toMicrosoft.DocAsCode.Common
. The copied classes in projectMicrosoft.DocAsCode.Utility
are kept there for bits compatibility and markedObsolete
. - Add command option
docfx -v
to show version of DocFX - Bug fixes:
- concurrency issue of
Logger
. - unable to handle file link with query string.
- unable to resolve uid for in html
<a href="xref:...">
. - display specName wrong for generic type. (dotnet#896)
- breadcrumb rendered wrong when multiple toc item matched.
- subcommand metadata can't specify DocFX config file
- concurrency issue of
- Fix bookmark validation failed when link contains illegal characters.
- Fix xref to fall back to uid.
- Fix xref with query string not resolved.
- Fix relative path when validating bookmark.
- Search embedded resource prior to local resource.
- Improve markdown engine performance.
- Improve regex.
- Add regex timeout.
- Fix bugs in markdown parser.
- Refine xref.
- Provide more options.
- Support options in query string.
- Support query string in toc href.
- Remove debug information in html.
- Add metadata command option to disable rendering triple-slash-comments as markdown.
- Fix bug in merging properties.
- Support extension for preprocessor file in default template. (dotnet#662)
- Improve error/warning message.
- Support bookmark validation.
- minor: fix the Renderer
- Improve markdown engine performance.
- Improve regex.
- Add regex timeout.
- Fix bugs in markdown parser.
- DFM: Support code in table
- Fix argumentnullexception for generating overload item.
- Add serializable attribute.
- Use mark.js to highlight keywords.
- Remove rest resolved cache.
- Fix assert fail in metadata. (dotnet#741)
- Add new command option: repositoryRoot.
- Fix isssue #719 that assertion failed.
- Update documenation
- Remove debug build option in Release configuration
- Fix error message for invalid file link.
- Support attribute filter to filter out attributes.
- Support choosing git URL pattern. (dotnet#677)
- Fix bug for line number is 0.
- Add source file and line number for warning invalid file/uid link.
- Fix bugs in markdown table.
- Update default template theme.
- Fix resolving properties for swagger.
- Fix bugs in markdown.
- Fix id in title (following GitHub rule).
- Fix strikeout not work in dfm.
- Fix tight list item behavior.
- Fix line number in table.
- Support emoji in markdown content.
- Upgrade yamldotnet to 3.9.
- Refine markdown validation.
- Support separated meta json file.
- Change
hightlight.js
theme togithub-gist
. - Support '.json' as supported swagger file extension.
- Support
topicHref
andtocHref
to specify homepage toc. - Support customized contribute repository and branch for "Improve this Doc" button. (dotnet#482)
- Improve message for
docfx.exe template
command.
- Fix bug in
.manifest
file.
- Fix bug when metadata incremental check.
- Move post process out of DocumentBuilder.
- Support multi-version site. (dotnet#396)
- Support loop reference for Swagger Rest API. (dotnet#223)
- Support plug-in for post processor.
- Support href for see/seealso tags.
- Improve API reference documentation of namespace and enum.
- Update prerequisite to build docfx.
- Update manifest schema.
- Add chocolatey support in CI script.
- Provide with options in build.cmd.
- Bug fixes:
- syntax for static class is incorrect.
- improve warning message about global namespace class. (dotnet#417)
- fix normalizexml bug for empty
<code></code>
in tripleslashcomment.
-
Support for xref zip file in relative path.
-
Support anchor in toc file.
-
Support plug-in for validating markdown input metadata.
-
Add output file md5 hashes.
-
Breaking Url Rename generic type file name in metadata step
E.g.
System.Func<T>
will generateSystem.Func-1.yml
instead ofSystem.Func`1.yml
, and after build the url will beSystem.Func-1.html
instead ofSystem.Func%601.html
.To keep old behavior, please add following option in metadata part in docfx.json:
"useCompatibilityFileName": true
-
Display extension methods in API reference documentation
-
Provide with option
_displayLangs
in docfx.json to choose which language version you want to show. -
Support more Swagger syntax:
- Support
allOf
. (dotnet#360) - Support $ref with
[
and]
in json pointer. (dotnet#359) - Support
parameters
applicable for all the operations underpath
. (dotnet#358)
- Support
- Support localization tokens in DFM.
- Fix bug that file links can't be resolved in overwrite file
- Breaking Change Add line info for markdown parser.
- Allow Markdown reference at the end of overwrite file.
- Provide more information for API reference documentation
- display inherited members
- display overridden members
- display implemented interface
- separate category for Explicit Interface Implementation
- Rest api - Enable Tag in Swagger file to organize the APIs.
-
Breaking Change Refactor template system:
- The input data model now contains all the properties including system generated metadata starting with underscore
_
and globally shared variables stored in__global
. You can usedocfx build --exportRawModel
to view the data model. - Preprocessor's
transform
function signature changes to:
exports.transform = function (model){ // transform the model return model; }
- The input data model now contains all the properties including system generated metadata starting with underscore
-
Provide a new embedded template
statictoc
with TOC generated in build time. Webpages generated by this template is PURE static and you can simply open the generated webpage file to take a preview, no local server is needed. -
Allow switch markdown engine.
-
Allow export metadata to manifest file.
-
Improve
exclude
logic to help avoidPathTooLongException
. (dotnet#156) -
Provide with a config file named
search-stopwords.json
to customise full-text search stop-words. (dotnet#279) -
Bug fixes:
- Fix bug when cref contains loop. (dotnet#289)
- Make sure id is unique for each HTML in markdown transforming. (dotnet#224)
- Fix index range bugs in
YamlHeaderParser
. (dotnet#265)
- Fix bug when outputFolder, basedirectory and destination are all not set
- fix
<a>
tag when href has invalid value with anchor
- Fix bug for [!include()[]] when multiple articles in different subfolder including one file that v1.8.2 not resolved
- Fix bug for [!include()[]] when multiple articles in different subfolder including one file
- Fix bug when serialize attribute argument for type array. (dotnet#280)
- Fix bug when include file link to an anchor.
- Don't modify link when target file not existed.
- Support multiple regions selection, code lines highlight and dedent length setting in Code Snippet. (dotnet#189)
- Support more tags in triple-slash-comments, e.g.
lang
,list
,code
,paramref
andtypeparamref
. - Add Example section to default template.
- Bug fixes:
- Fix bug when parsing triple-slash-comments. (dotnet#221)
- Fix syntax generation for VB module. (dotnet#260)
- Behavior change
- For articles not in TOC, it's TOC file is the nearest TOC File in its output folder. Previously we only search the TOC File under the same input folder of the Not-In-Toc article.
- Provide more information for API reference documentation
- Type of events (dotnet#217)
- Parameters/returns for delegates (dotnet#218)
- Type parameter description (dotnet#204)
- Cross-reference is now supporting anchor
#
(dotnet#190) - C# Code snippet now supports referencing source code using a region
#engion
(dotnet#160) - Support TOC reference. With this syntax, we can combine multiple TOC files into a single TOC. (dotnet#161)
- Improve user experience when using
docfx.msbuild
in VS IDE - Code refactor:
- We improved DocFX project structure in this release.
Microsoft.DocAsCode.EntityModel
namespace is no longer in use. Assemblies are separated intoMicrosoft.DocAsCode.Build
,Microsoft.DocAsCode.DataContracts
, andMicrosoft.DocAsCode.Metadata
namespace. All assemblies can be separately referenced through NuGet. In this way, it is much convenient for plugin writers to reference existing data models and utilities.
- We improved DocFX project structure in this release.
- Add attribute in c# and vb syntax.
- Support full text search, with pure client side implementation:
- The feature is disabled by default. You can enable it by adding
"_enableSearch": true
to theglobalMetadata
property ofdocfx.json
. - The search engine is powered by lunr.js
- The feature is disabled by default. You can enable it by adding
- Add 3 options to
build
subcommand:--rawModelOutputFolder
: to specify the output folder for raw model if--exportRawModel
. If the value is not set, raw model will be in the same folder as the output documenation.--viewModelOutputFolder
: to specify the output folder for view model if--exportViewModel
. If the value is not set, view model will be in the same folder as the output documenation.--dryRun
: if this option is set,docfx
will go through all the build processes for all the documents, however, no documentation will generated.
- Improve markdown:
- Allow paired parentheses in link target, e.g.
[text](paired(parentheses(are)supported)now "title")
.
- Allow paired parentheses in link target, e.g.
- Improve performance for document build.
- Breaking changes:
- modify interface @Microsoft.DocAsCode.Plugins.IDocumentBuildStep.
- Fix bug for encoded link file.
- Fix bug for directory not found.
Remove newFileRepository
from output metadata
-
Cross-reference related:
-
Make @uid rule more strict: if
@
is not followed by'
or"
, it must be followed by word character ([a-zA-Z]
) -
Introduce new syntax for cross-reference:
- similar to autolink:
<xref:uid>
- similar to link:
[title](xref:uid)
or[title](@uid)
- similar to autolink:
-
support
uid
intoc.yml
:- uid: getting-started - uid: manual
-
support cross reference in
toc.md
# <xref:getting-started> # [Override title](@getting-started)
-
-
Update yaml serializion: Add @Microsoft.DocAsCode.YamlSerialization.ExtensibleMemberAttribute
-
Improve
docfx init
, now withdocfx init
, adocfx_project
seed project will will generated. -
Several improvements for
default
template:- Provide properties to customize layout:
_disableNavbar
,_disableBreadcrumb
,_disableToc
,_disableAffix
,_disableContribution
,_disableFooter
- Include empty
main.css
andmain.js
tohead.tmpl.partial
partial template so that there is no need to customizehead.tmpl.partial
when you want to customize website style.
- Provide properties to customize layout:
Fix no link and ref link cannot work issue in table
- Fix no link and ref link cannot work issue in markdownlite.
- Fix link issue (allow space in link) in markdownlite.
- Fix para for list in markdownlite.
- Fix tokenize bug in dfm.
- Add markdown token validator in dfm.
- Fix cross domain issue: timeout exception throws when document build takes longer than 15 minutes
- Fix docfx IOException when calling
docfx -l report.txt
FIX Github pages compatibility issue( Github pages now disallow iframe, however the default template of docfx
uses iframe to load side toc): Update default template to use AJAX to load side toc, the original one is renamed to iframe.html
. So now we have 2 embedded template, one is default
and another is iframe.html
.
docfx
improvements- Add subcommand
docfx template
. You can nowdocfx template list
anddocfx template export -A
to list and export all the embeded templates! - Add subcommand
docfx merge
. You can use this subcommand to mergeplatform
from multiple APIs with the sameuid
- Add two options to
build
subcommand,--exportRawModel
and--exportViewModel
.--exportRawModel
exports the data model to apply templates,--exportViewModel
exports the view model after running template's pre-process scripts. - Add
--globalMetadata
, and--globalMetadataFile
options tobuild
subcommand. These options allowglobalMetadata
to be loaded from command line in json format or from a JSON file. - Add
--fileMetadataFile
option tobuild
subcommand. This option allowsfileMeatdata
to be read from an external JSON file. - Support plugins. You can create your own template with a
plugins
folder, inside which, you create your own build steps. Refer to @Microsoft.DocAsCode.EntityModel.Plugins.BaseDocumentBuildStep for a sample plugin implementation.
- Add subcommand
- DFM syntax improvements
- Support note&div syntax
- Support query format in code snippet
[!code-<language>[<name>](<codepath><queryoption><queryoptionvalue> "<title>")]
- Change xref logic:
- If content after
@
is wrapped by'
or"
, it contains any character including white space - If content after
@
is not wrapped by'
or"
, it ends when:- line ends
- meets whitespaces
- line ends with
.
,,
,;
,:
,!
,?
and~
- meets 2 times or more
.
,,
,;
,:
,!
,?
and~
- If content after
- Code improvements
- Add @Microsoft.DocAsCode.YamlSerialization This project is based on YamlDotNet. It overrides classes like type converters to improve performance and fix bug existed in YamlDotNet
- Refactor markdown engine @Microsoft.DocAsCode.MarkdownLite
- Add @Microsoft.DocAsCode.MarkdownLite.IMarkdownRewritable`1. It provides a way to operate markdown tokens.
- Other improvements
- Add a new property
_path
into_attrs
, it stands for the relative path fromdocfx.json
to current file - Improve missing xref warning message to include containing files.
- Add
data-uid
as attribute to generated html from default template, so that you can now finduid
for API much more easily.
- Add a new property
- Support Liquid template, templates ending with
.liquid
are considered as using liquid templating language. Liquid containsinclude
tag to support partials, we follow the ruby partials naming convention to have_<partialName>.liquid
as partial template. A custom tagref
, e.g.{% ref file1 %}
is introduced to specify the resource files that current template depends on. - DFM include syntax is updated to use
[!include[<title>](<filepath>)]
syntax - Disable glob pattern in
docfx metadata
command line option as it is to some extent confusing, consider using a-g
option later to re-enable it.
- Rewrite Glob
The syntax of glob is:
**
is called globstar, it matches any number of characters, including/
, as long as it's the only thing in a path part.- If
**
is right behind/
, it is a shortcut for**/*
. *
matches any number of characters, but not/
?
matches 1 characters, but not/
{}
allows for a comma-separated list of "or" expressions, e.g.{a,b}
=>a
andb
!
at the beginning of a pattern will negate the match[...]
matches a range of characters, similar to a RegExp range/
is considered as path separator, while\
is considered as escape character
- Support
fileMetadata
. You can specify different metadata value using glob pattern - Improve overwrite functionality. Now you can overwrite not only summary/remarks, but also descriptions for parameters. You can even add exceptions.
- Now the latest project.json projects are also supported in DNX version.
- Simple code snippet is now supported, syntax is
[!code-REST-i[title](path "optionalTitle")]
- Url is now encoded in markdown link.
- Add section syntax in DFM
- Fix several bugs in DFM
- Update default template: rename css/js file
- Fix several display issue in default template
- Support Static Website Templates
- Schema change to docfx.json