Docs(docfx): update docfx build locally guide and apply xref links #19722

DevTKSS · 2025-03-21T03:39:55Z

GitHub Issue (If applicable): closes #

PR Type

What kind of change does this PR introduce?

Bugfix
Feature
Code style update (formatting)
Documentation content changes
Build or CI related changes (maybe?)

What is the current behavior?

Current docfx guide is outdated and telling to use docfx.console which has been depreciated
see more Information to this here: dotnet/docfx#9100
Link to the Documentation page
The Uno.Extensions Repository is already having the new commands in its Readme.md

Secondary, the check_toc.ps1 does list almoast every href as not linked to a file, because it does not recognize the xref link declaration

Third page is way smaller changes:

The Getting-started did not at all mention the need to install dotnet before Uno.Check (that is only told on the actual Uno.Check Page) so thats more a reason of completeness of the Quick Start.
I did frequently notice Beginners ask about Trouble-Shooting Uno.Check and since we did already seperate its Pages (much better from my point of view!) there has been those links been missing.

What is the new behavior?

Updated the docfx commands
- I did left there some commented text, which needs to be checked if the new one is enough.
  Problem with that is, I do not understand the UWPSyncGenerator so deeply to decide this. Currently, those comments do stretch the md line distance a bit (vs 2022 preview) althought its hidden.
Added a detailed guide to the usage of check_toc.ps1 along with adding the capability of recognizing and comparing the xref -> uids

By this it also did uncover the features/windows-xaml-ui-xbind link beeing broken, I did already wonder last days. Was unable to navigate to this page in the docs.
Second link it did uncover is the only url link in toc and to me it looks okay, but maybe someone would like to check this...
Another Link I do not know if the url is correct is the now nested Uno.Check Pages I tryed to link from the Getting-Started.
The old one does have a different signature...
Because of that new capability of the script, I added a -Verbose Flag for it, so in case of problems, there would be informations available, till which point it came.
Help needed with the Link to the gif I added to this for showing a workaround for those who might not know these steps until this point, to find not inluded files in vs 2022. I used the docfx documentation way for Image, but its showing only a broken image symbol...
I dont know if the script change does actually make this to a CI - Build relevant PR but there is told: At the moment it's not part of the CI, so I dont know it should be tested for this again...

PR Checklist

Please check if your PR fulfills the following requirements:

Docs have been added/updated which fit documentation template (for bug fixes / features)
Unit Tests and/or UI Tests for the changes have been added (for bug fixes / features) (if applicable)
Validated PR Screenshots Compare Test Run results. -> building docfx is failing because of missing things it seems to me
docfx build output.txt
Contains NO breaking changes -> would not identify it as such...
Associated with an issue (GitHub or internal) and uses the automatic close keywords. -> I did not see one just my problem with it.
Commits must be following the Conventional Commits specification.

Other information

Above mentioned

Internal Issue (If applicable):

unodevops · 2025-03-21T05:35:46Z

⚠️⚠️ The build 158236 has failed on Uno.UI - docs.

DevTKSS · 2025-03-21T07:29:38Z

The markdown linting pipeline in this case would be greatly more helpful if it would also lint and suggest the solution for image video and links like relative paths and so on before the intending and spaces checks👍🤔

unodevops · 2025-03-22T20:35:15Z

⚠️⚠️ The build 158359 has failed on Uno.UI - docs.

DevTKSS · 2025-03-24T11:12:59Z

Currently on Fixing a regex bug, then I will send the updated commits.
Had to delete the commented parts mentioned to satisfy the markdown lints, hopefully anyone could check then if there needs to be something added in relation to the UwpSyncGenerator.

DevTKSS · 2025-03-24T11:21:31Z

Does a include of Pester tests required check the ui tests checkbook above?
Adding those for the functions of check_toc.ps1 which I now seperated (incl. Documentation of course) to check still listed toc items that I was quite sure that they are linked🤣
But since docfx is still failing to serve because of doc issues in the external nested stuff I am not able to review docs locally😒

agneszitte · 2025-03-24T15:06:19Z

@DevTKSS Thank you so much for the Pull Request ❤️
I will take the time to review the changes this week and follow up with you as needed

DevTKSS · 2025-03-25T09:15:35Z

Status update:
Two of three seperated functions of the script to recognize xref and uid plus to compare them did pass successfully the tests

Things might to consider for add able tests and function for uid-xref links:

casing
minus between uid allowed but no spaces
...

Currently checking on the dot sourcing third script now which should be last before again check on the main script which uses them.

The dot sourcing one might be the most difficult one to setup test for because it has no actual function definition right now, just what it should execute. If it works but test setup has still trouble with its validation I would consider updating the related docs on it and commit to the remote branch so its review-able and maybe get a overseen solution for this.

Since I did add those md files, I did sort them into directory and recognized that not really matching and seperated directorys. Seems like there is the main contributing one and the uno-development one which mainly contains all of the files nested in toc contributing😅
@agneszitte is it considerable to move the documentation related ones at least with git mv so source control has no issues but this setup follows the toc definition?

And I am thinking of, if the scripts might be better places to the testscrips folder instead(paths naturally fitted) to not cloud the documentation itself?

DevTKSS · 2025-03-26T07:30:33Z

@agneszitte @MartinZikmund commited to remote, unable to fix the Import-TocCheckerUtils.Test.ps1 to pass the check of Get-MarkdownHeader function, while it passed the dot-sourcing before. checking this here:

PS C:\Users\TKSSonja\Projects\uno\doc\articles\check-toc-utilities> . .\Get-MarkdownHeader.ps1
PS C:\Users\TKSSonja\Projects\uno\doc\articles\check-toc-utilities> Get-Command -Name "Get-MarkdownHeader" -CommandType Function

CommandType Name Version Source

Function Get-MarkdownHeader

PS C:\Users\TKSSonja\Projects\uno\doc\articles\check-toc-utilities>

It should have been able to get it from my point of view.
Could someone have a look on this and find the culprit?

unodevops · 2025-03-26T07:51:29Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

DevTKSS · 2025-03-26T08:36:50Z

ToDo List to be checked:

1. Enhance ./uno/doc/articles/index.md npm guide by adding tabbed content to choose from and include vs code extension options for this
- 1.1. cspell
- 1.2. markdownlint
- 1.3. adding links to ./uno/build dictionary/ preset files
Remove the Toc checker added capabilities scripts again, since that had been replaced with Link validations #18029 as CI/CD task and not to the contributor locally any longer
Check for markdown and spelling using above mentioned tools
Check linted and then updated xref links
Moved files to their namespace folders (this is causing the high number of file changes)

doc/articles/check-toc-utilities/Guide.md

doc/articles/contributing/Documentation/anchor-links.md

doc/articles/contributing/guidelines/creating-ps-pester-tests.md

doc/articles/uno-development/doc-on-docs.md

doc/articles/uno-development/docfx.md

doc/articles/check-toc-utilities/Overview.md

doc/articles/check-toc-utilities/Guide.md

doc/articles/toc.yml

unodevops · 2025-03-28T17:36:06Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

DevTKSS · 2025-03-28T18:13:30Z

work still in progress

unodevops · 2025-03-28T18:56:32Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

unodevops · 2025-03-28T21:09:57Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/index.html

unodevops · 2025-03-31T23:45:16Z

⚠️⚠️ The build 159133 has failed on Uno.UI - docs.

unodevops · 2025-03-31T23:46:05Z

⚠️⚠️ The build 159134 has failed on Uno.UI - CI.

DevTKSS · 2025-04-01T17:17:24Z

checked the "Run spell checking" pipeline problems, seems the CI needs some external help to ignore this or tell me and I switch the xref Names there, but since that are not my created ones and most likly be linked at some places, I would prefer decision from the team for this...
@agneszitte can you give me that advise you/uno prefers?

Lines:

  - name: Layouting in iOS
    href: xref:Uno.Contributing.LayoutingiOS

  - name: Building Uno.UI for macOS using Visual Studio for Mac
    href: xref:Uno.Contributing.BuildingUnomacOS

  - name: Guidelines for implementing a new WinUI/WinRT feature
    href: xref:Uno.Contributing.ImplementWinUIWinRTAPI

- name: Design-to-Code
  href: external/figma-docs/toc.yml

- name: Uno Resizetizer
  href: external/uno.resizetizer/doc/toc.yml

  - name: Omnisharp Support
    href: xref:Uno.GetStarted.vscode.OmniSharp

Post Edit Note: Renaming has been applyed for xref of 1-3, others got added to cspell. See this commit for details

unodevops · 2025-04-01T20:35:19Z

⚠️⚠️ The build 159337 has failed on Uno.UI - docs.

unodevops · 2025-04-01T21:36:05Z

⚠️⚠️ The build 159338 has failed on Uno.UI - CI.

unodevops · 2025-04-02T17:27:16Z

🤖 Your WebAssembly Sample App stage site is ready! Visit it here: https://unowasmprstaging.z20.web.core.windows.net/pr-19722/index.html

Rider Android Support is reported as incompatible as of 06.02.2025 should get checked and until then removed

…aces

unodevops · 2025-07-05T22:47:24Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/docs/index.html

…ut vs code extensions

unodevops · 2025-07-05T23:09:34Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/docs/index.html

DevTKSS · 2025-07-05T23:15:31Z

@agneszitte @Jen-Uno @MartinZikmund (as you reviewed initially)
finalized this PR and its smallered its commit count and containment. From my side Ready to be reviewed 👍

Check this comments for a overview:

To be checked from the Team:

These Pages/Files are obviously including outdated information, as of v6 Major Version:

Passwort Vault doc page - Platform Win 7 and targets. windows docs are saying its implemented for windows (just like our docs), but that incapability is filed for Skia Desktop so thats something I can not difference to be possible with our new Win32
unoplatform/uno Github Main Readme seems like miss information as by the 6.0
I added a Comment to the appropriate section, so you can check. As this is the uno platform advertising point No 1 beneath the Homepage, it would make defintly sense, to add the great news for Hot Design and SkiaRenderer also there and we have the win 7 there also still filed as available platform
You do file in the Readme

The SQLite + Entity Framework Core App, a demo of the combination of Roslyn, Entity Framework Core, SQLite and the Uno Platform to manipulate an in-browser database.
But this is not having current documentation for a how to beside the Migration from Silverlight docs, that the search index of the docs would show? I would indeed LOVE to have an option or/and guide for using a (maybe also MySql or similar DB), because I am searching for this right now, to integrate it on my serverside-wasm target ❤️

Maybe you could have also a look in general, if we could get the markdownlint.json to a .jsonc format (CI flow change therefore this should be checked from Team side) so the lintings and errors showing up there from the // comments in it, would get fixed 👍

doc/.howto-template.md

doc/README.md

DevTKSS · 2025-07-07T16:00:24Z

doc/articles/contributing/guidelines/updating-dependencies.md

+<!-- TODO: decide if following line should be changed, since docfx.console is officially depreciated! -->
 - [docfx.console](https://github.com/unoplatform/Uno/pull/1082/commits/c222caf8c23b35e19f6b33cd624cbfa714250bfe)


@booskander could you check on this?

doc/README.md

chore: moved the gif file to the assets folder near to the file its used with chore: added the Anchor Links Link to the toc used replace in vs code which should have found all occurrences

unodevops · 2025-07-07T17:59:28Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/docs/index.html

…ocally-guide

unodevops · 2025-07-08T23:45:33Z

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-19722/docs/index.html

DevTKSS · 2025-07-19T17:53:58Z

@jeromelaban would guess here is just that one comment to be checked and seems like bootscander is out of office, do you see anything left to do here?

github-actions · 2025-09-18T02:04:13Z

This PR is stale because it has been open 60 days with no activity. Remove stale label or comment or it will be closed in 10 days.

DevTKSS · 2025-09-18T11:21:07Z

@Jen-Uno can you give me some state update on this or what I might need to change to get this finished up and merged/dropped?

github-actions bot added area/build Categorizes an issue or PR as relevant to build infrastructure kind/documentation labels Mar 21, 2025

MartinZikmund approved these changes Mar 26, 2025

View reviewed changes

agneszitte added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 27, 2025

agneszitte reviewed Mar 27, 2025

View reviewed changes

doc/articles/check-toc-utilities/Overview.md Outdated Show resolved Hide resolved

agneszitte reviewed Mar 27, 2025

View reviewed changes

doc/articles/check-toc-utilities/Guide.md Outdated Show resolved Hide resolved

agneszitte reviewed Mar 27, 2025

View reviewed changes

doc/articles/check-toc-utilities/Guide.md Outdated Show resolved Hide resolved

agneszitte reviewed Mar 27, 2025

View reviewed changes

doc/articles/toc.yml Outdated Show resolved Hide resolved

DevTKSS force-pushed the docs(DocFx)-update-run-docfx-locally-guide branch from dcc12c5 to 8d6e32f Compare March 31, 2025 17:32

DevTKSS added 3 commits July 6, 2025 00:09

docs(templates): Remove very outdated information

111cda4

Rider Android Support is reported as incompatible as of 06.02.2025 should get checked and until then removed

chore(PasswordVault): Adjust pipe table markdown and trailing whitesp…

d5cbdd3

…aces

chore: Check broken links and information to be current in Readme

e91216c

DevTKSS force-pushed the docs(DocFx)-update-run-docfx-locally-guide branch from d2166e3 to e91216c Compare July 5, 2025 22:12

DevTKSS changed the title ~~Docs(docfx): update docfx build locally guide and enhance check-toc capabilitys~~ Docs(docfx): update docfx build locally guide and check xref links Jul 5, 2025

DevTKSS changed the title ~~Docs(docfx): update docfx build locally guide and check xref links~~ Docs(docfx): update docfx build locally guide and apply xref links Jul 5, 2025

chore(testingPS): update Links and remove dropped commits content links

dd335cb

chore: update doc Readme for contributor markdown and information abo…

28cd73d

…ut vs code extensions

DevTKSS requested review from MartinZikmund and agneszitte July 5, 2025 23:18

Jen-Uno requested review from booskander and removed request for MartinZikmund and agneszitte July 7, 2025 14:38

booskander reviewed Jul 7, 2025

View reviewed changes

doc/.howto-template.md Outdated Show resolved Hide resolved

doc/README.md Outdated Show resolved Hide resolved

DevTKSS commented Jul 7, 2025

View reviewed changes

doc/README.md Outdated Show resolved Hide resolved

DevTKSS added 2 commits July 7, 2025 18:06

chore: Update link

1ef10a8

chore(DocFx): Apply casing update to match lowercasing

003610c

chore: moved the gif file to the assets folder near to the file its used with chore: added the Anchor Links Link to the toc used replace in vs code which should have found all occurrences

DevTKSS requested a review from booskander July 7, 2025 18:15

Merge branch 'unoplatform:master' into docs(DocFx)-update-run-docfx-l…

7670f57

…ocally-guide

github-actions bot added the stale This item has been marked as stale and will be closed if there is no activity. label Sep 18, 2025

github-actions bot removed the stale This item has been marked as stale and will be closed if there is no activity. label Sep 19, 2025

		<!-- TODO: decide if following line should be changed, since docfx.console is officially depreciated! -->
		- [docfx.console](https://github.com/unoplatform/Uno/pull/1082/commits/c222caf8c23b35e19f6b33cd624cbfa714250bfe)

Docs(docfx): update docfx build locally guide and apply xref links #19722

Are you sure you want to change the base?

Docs(docfx): update docfx build locally guide and apply xref links #19722

Uh oh!

Conversation

DevTKSS commented Mar 21, 2025

PR Type

What is the current behavior?

What is the new behavior?

PR Checklist

Other information

Uh oh!

unodevops commented Mar 21, 2025

Uh oh!

DevTKSS commented Mar 21, 2025

Uh oh!

unodevops commented Mar 22, 2025

Uh oh!

DevTKSS commented Mar 24, 2025

Uh oh!

DevTKSS commented Mar 24, 2025

Uh oh!

agneszitte commented Mar 24, 2025

Uh oh!

DevTKSS commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DevTKSS commented Mar 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unodevops commented Mar 26, 2025

Uh oh!

DevTKSS commented Mar 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

unodevops commented Mar 28, 2025

Uh oh!

DevTKSS commented Mar 28, 2025

Uh oh!

unodevops commented Mar 28, 2025

Uh oh!

unodevops commented Mar 28, 2025

Uh oh!

unodevops commented Mar 31, 2025

Uh oh!

unodevops commented Mar 31, 2025

Uh oh!

DevTKSS commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

unodevops commented Apr 1, 2025

Uh oh!

unodevops commented Apr 1, 2025

Uh oh!

unodevops commented Apr 2, 2025

Uh oh!

unodevops commented Jul 5, 2025

Uh oh!

unodevops commented Jul 5, 2025

Uh oh!

DevTKSS commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Check this comments for a overview:

To be checked from the Team:

Uh oh!

Uh oh!

DevTKSS commented Mar 25, 2025 •

edited

Loading

DevTKSS commented Mar 26, 2025 •

edited

Loading

DevTKSS commented Mar 26, 2025 •

edited

Loading

DevTKSS commented Apr 1, 2025 •

edited

Loading

DevTKSS commented Jul 5, 2025 •

edited

Loading