ellerbach / docfx-companion-tools Goto Github PK
View Code? Open in Web Editor NEWA suite of tools, pipelines templates to take the very best of DocFX
License: MIT License
A suite of tools, pipelines templates to take the very best of DocFX
License: MIT License
Hello,
I don't understand why the index.md
files are ignored by TocDocFxCreation and don't appear in the toc file ?
Regards,
Jonathan
I added a Linux tab and a Windows tab to a sample page using the example from the DocFX documentation below.
https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#tabs
When running DocLinkChecker against this page, I receive the following two warnings.
DocLinkChecker version 1.18.0
***WARNING Heading 'tab/linux' not found in 'D:\a\docfx\docfx\docs\guides\index.md'
***WARNING Heading 'tab/windows' not found in 'D:\a\docfx\docfx\docs\guides\index.md'
Can DocLinkChecker be updated to ignore the links associated with Tabs?
When running DocLinkChecker it appears that the checker doesn't understand or find the links if I am using a file inclusion with a Code Snippet.
These links are rendered just find by docfx however DocLinkChecker believes they are an error.
As an example, if I have the following structure:
doc/
index.md
docfx.json
scripts/
foo.cs
and foo.cs has the following content like this:
// (other content above)
// <Bravo>
foreach(var thing in list)
{
// Do Stuff
}
// </Bravo>
I can include the entire file with:
[!code-csharp[Code](~/Scripts/foo.cs)]
But this will be detected as an error by DocLinkChecker:
[!code-csharp[Code](~/Scripts/foo.cs?name=Bravo)]
In the screenshot attached, if there is a child folder that is basically contains no direct child .md files but has child folders that contain .md files it appears that those children are completely omitted from processing. Also, I noticed that in this scenario if you attempt the multitoc generation option the tool crashes with an exception.
We use this extension to generate toc.yml
for Python documentation using Sphinx. In this case, we want the toc titles to be exactly the same as that of the filename.
This feature request is to add a configuration option to skip automatic title casing for toc titles.
We could generate an .override file but the feature I propose is more efficient.
.NET 8 has been released very recently and it is obvious but .NET 7 why not?
Everything that manages our pipeline targets .NET 7 and just for this tool I have to install the .NET 6 runtime.
Would you accept a PR that targets .NET 7 (and .NET 8 if you want)?
Thanks!
The error:
You must install or update .NET to run this application.
App: /home/ci/.dotnet/tools/DocLinkChecker
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '6.0.0' (x64)
.NET location: /home/ci/data/agent/_work/_tool/dotnet
The following frameworks were found:
7.0.14 at [/home/ci/data/agent/_work/_tool/dotnet/shared/Microsoft.NETCore.App]
Great utility. It would be great if it could recursively traverse subfolders of the specified directory looking for markdown and .attachments in each folder found. In our DocFx, we put documentation for each component into their own folders, each also has it's own attachments folder. It's possible to script repeated calls but would be great to have it built in.
When validating for orphaned resources, errors are shown as '../../../' or something similar. This is because of an error in the sequence of parameters for calculating the relative path. Need to be fixed.
I am trying to integrate doclinkchecker and I am getting this error
./platform/Admin/Action-Hub/BuildAnAction.md 54:1
***ERROR Not found: ~/.attachments/image-ac695c92-679c-4bb6-9ce8-f02e64d6308e.png
Now the problem is that the file is there. Its even visible when I publish the generated website.
I am just not sure how to troubleshoot this. I saw #12 brought support for ~
When generating toc's with the following params:
-s -r -m 1 -g -v -i
The TOC's that get generated will contain duplicate entries for a folders index.md
With the following folder structure:
> docs
- index.md
> manual
- index.md
> folderA
- index.md
- example1.md
- example2.md
> folderB
- index.md
- example.md
I get the following toc.yml
in the manual
folder:
items:
- name: Manual
href: index.md
- name: FolderA
href: FolderA/index.md
items:
- name: FolderA <------ POINTLESS!
href: FolderA/index.md <------ POINTLESS!
- name: Example 1
href: FolderA/example1.md
- name: Example 2
href: FolderA/example2.md
- name: FolderB
href: FolderB/index.md
items:
- name: FolderB
href: FolderB/index.md
- name: Example
href: FolderB/example.md
When I build this the problem becomes more obvious. Index files are essentially listed twice. Once as the "foldout" then again as an item inside the foldout:
If I delete the duplicate items in the toc.yml
's and re-build it all works correctly:
When using a glob pattern for documentation files (e.g. src=., files = /docs//*.md), using just ResourceFolderNames doesn't work. The entire tree of src is scanned for all folders with the name assets or images, instead of in /docs//images/**" for instance. Need resources files to a list of glob patterns as well to make this work properly.
The currently solution works perfectly if just using against 1 /docs hierarchy btw.
Hey there, love the utilities!
I routinely hop between Windows and macOS, and noticed while there's binaries published for Windows in this repo and on Chocolatey, there's none published for macOS or on Homebrew. Currently I'm pulling the source and rebuilding against macOS instead of Windows. I was wondering if in addition to Windows binaries, if there could be consideration in publishing release artifacts for macOS and Linux going forward as well. I can help with a PR if desired.
In the [!NOTE] tag a space get's inserted right after the exclamation mark.
[!NOTE] becomes [! NOTE]
Hi
I'm trying to install the tool using the recommended command choco install docfx-companion-tools
but it fails with the following error:
Failures
- docfx-companion-tools - docfx-companion-tools not installed. The package was not found with the source(s) listed.
Source(s): 'https://chocolatey.org/api/v2/'
NOTE: When you specify explicit sources, it overrides default sources.
If the package version is a prerelease and you didn't specify `--pre`,
the package may not be found.
Please see https://docs.chocolatey.org/en-us/troubleshooting for more
assistance.
Any ideas regarding how this can be fixed? :)
See https://megalinter.io/latest/plugins/
Megalinter allows to create plugin. This can be a nice and convenient way to get the tools integrated in a larger linter infrastructure.
Given this directory structure:
Running DocFxTocGenerator.exe --docfolder DocFxIndex --index
, the toc.yml contains:
items:
- name: DocFxIndex
href: index.md
- name: A
href: A/B.md # links to B.md instead of index.md
items:
- name: A
href: A/index.md # generated
- name: B
href: A/B.md
The root-level item "A" links to A/B.md
, because at generation-time the A/index.md
didn't exist yet.
Running the TOC generator a second time fixes that:
items:
- name: DocFxIndex
href: index.md
- name: A
href: A/index.md # now links to A/index.md
items:
- name: A
href: A/index.md # there's A/index.md again!
- name: B
href: A/B.md
Now the TOC contains "A/index.md" twice, resulting in weird nesting in the menu, mentioning "A" twice:
I would expect:
--index
is stable).So:
items:
- name: DocFxIndex
href: index.md
- name: A
href: A/index.md # immediately links to the generated index
items:
# doesn't mention it again as child item
- name: B
href: A/B.md
Please add DocLinkChecker support for using the ~
character to represent relative paths from the root of a DocFX project.
This is essential for deeper project structures that utilize the .attachments
folder at the root of a project.
This behavior is also officially supported by DocFX, but results in a failure using the companion tool suite:
Not found: ~/.attachments/abc.png
From the DocFX Tutorial page on Links and Cross References:
Sometimes you may find it's complicated to calculate relative path between two files. DocFX also supports paths that start with ~ to represent a path relative to the root directory of your project (i.e., where docfx.json is located). This kind of path will also be validated and resolved during build.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.