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

[DevTKSS]

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?

1. 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.

2. 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]

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

[DevTKSS]

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]

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

[DevTKSS]

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]

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]

@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]

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]

@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]

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

[DevTKSS]

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)

[unodevops]

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

[DevTKSS]

work still in progress

[unodevops]

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

[unodevops]

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

[unodevops]

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

[unodevops]

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

[DevTKSS]

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]

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

[unodevops]

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

[unodevops]

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

[github-actions]

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]

@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?

[Copilot]

Pull Request Overview

This pull request updates the Uno Platform documentation to modernize the docfx build instructions and extensively applies xref cross-reference links throughout the documentation structure. The main changes focus on improving documentation maintainability and navigation.

Key Changes

• Updated docfx build commands from deprecated docfx.console to current docfx tool
• Converted numerous hard-coded documentation links to xref references for better maintainability
• Added multiple new documentation files covering topics like native views, native styles, composition API, performance, and more
• Restructured the table of contents (toc.yml) with improved organization and xref links
• Fixed casing inconsistency in code comments ("DocFx" → "docfx")

Reviewed Changes

Copilot reviewed 57 out of 139 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
doc/templates/uno/service/search.js	Fixed casing of "docfx" in comment (spelling correction)
doc/templates/uno/styles/docfx.js.map	Regenerated minified JavaScript map file
doc/index.md	Updated link to debugging guide using xref
doc/articles/uno-development/*.md	Added extensive new documentation files for native features, composition, performance, etc.
doc/articles/toc.yml	Major restructuring with xref links replacing hard-coded paths
doc/articles/getting-started/*.md	Added licensing documentation and supporting assets
doc/articles/features/windows-ui-markup-extensions.md	Removed trailing whitespace
Multiple PNG files	Added new screenshot assets for documentation

[unodevops]

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

[DevTKSS]

Pull Request Overview

...

Key Changes

...

• Added multiple new documentation files covering topics like native views, native styles, composition API, performance, and more

🤔 not really added those files, I just moved to the appropriate location if not already there. like creating contribution/documentation/ folder and moving the relevant docs files to.
you can check this in the PR overview for changed files if you want to.

Latest updates do introduce compared to the previously seen ones:

• Rebased on current state of Uno origin repo, so the PR does have the latest AI and Studio docs changes.
• TOC Checker script
  • check_toc.ps1 changes reverted
  • removed Utilities etc and replaced by the CI PR some while ago
  • Overview and Guide seperated to own file, connected via xref link
• Slight TOC structure improvements and file movement (as mentioned above) along the uid namespace of the files mainly Uno.Contributing.*, if the the handled topic did match this namespace and updating to use them for linking via xref.
  By doing this, this improves also the capability of Contributors like me, who might be searching for some topic to improve except from "edit this file" usage in the docs, when locally searching for the file. So the uno-development folder contains mostly the Topics that are not specifically to Contributing to Uno then to development with Uno ;)
• Gave the getting started image content its own seperated Assets folder inside of the /get-started/ chapter related folder
  • not moved the AI related get started files, just the IDE and vs extension specific get started

@Jen-Uno seeing your - #21828 so maybe you might want to cherry pick those movement commits until the team finds time to review this? 🚀

• Get-Started.md guide improvements to evaluate?
  • e0bba48
  • not sure how to split this one afterwards, but most movements done here + get started guide(s) improvements - 27b242a
• Movements of IDE Specific Get Started
  • 5de1c4d

[unodevops]

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

[DevTKSS]

@Jen-Uno seeing you create another docfx PR, so seems like this PR here is now obsolete? Would you be able to check if a rebase &update would make any longer sense or you just cherry pick what you need and we can have this closed in any future? its now open for month and not really funny to see PR + PR of the team doing the same themselfs and not noticing this any longer. 😅

[github-actions]

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.

[github-actions]

This PR was closed because it has been stalled for 10 days with no activity.