build(docs): Update api-markdown-documenter and utilize new hierarchy options #23504

Josmithr · 2025-01-08T18:38:43Z

Update dev dependency on @fluid-tools/api-markdown-documenter and leverage new "hierarchy" capabilities to move "folder" item documents (packages and namespaces) into their folders, renamed to index.

E.g.,
File structure before:

| fluid-framework.md
| fluid-framework
    | foo.md
    | ...

After:

| fluid-framework
    | index.md
    | foo.md
    | ...

This makes the breadcrumbs and navigation drop-downs generated by docusaurus better match the intended hierarchy.

E.g.,

Namespace appearance in the nav before:

Note that there is a separate page and folder, and selecting the folder doesn't navigate to the page; it just functions as a drop-down.

Namespace appearance after:

Breadcrumb before:

Note that the parent folder isn't selectable, because Docusaurus doesn't understand that it's supposed to point to the document of the same name.

Breadcrumb after:

Note that the parent entry is now selectable (screenshot was taken with mouse hovering over item)

AB#24263

…archy-fixes

Josmithr · 2025-01-23T19:24:37Z

docs/.gitignore

+docs/api
+!docs/api/index.mdx
+versioned_docs/*/api
+!versioned_docs/*/api/index.mdx


Opted to exclude specific files, rather than blanket-excluding mdx files. This will let us (theoretically) move our API docs to mdx in the future.

Josmithr · 2025-01-23T19:25:27Z

docs/docs/api/index.mdx

@@ -6,13 +6,13 @@ sidebar_position: 10

 {/* Note: these contents are new and should be reviewed. The current website's API docs landing page has no description about what the packages do / when to use them. It's not very useful. */}

-To get started with the Fluid Framework, you'll want to take a dependency on our client library, [fluid-framework](./fluid-framework.md).
+To get started with the Fluid Framework, you'll want to take a dependency on our client library, [fluid-framework](./fluid-framework/index.md).


We have to specify index here because we are expressing these links via file paths rather than routes. This is the recommended pattern.

docs/infra/api-markdown-documenter/render-api-documentation.mjs

Josmithr · 2025-01-23T19:28:23Z

docs/versioned_docs/version-1/api/fluid-framework.mdx

@@ -5,7 +5,7 @@ sidebar_label: fluid-framework

 # fluid-framework Package

-The fluid-framework package bundles a collection of Fluid Framework client libraries for easy use when paired with a corresponding service client package (for example, [@fluidframework/azure-client](/docs/deployment/azure-fluid-relay) or [@fluidframework/tinylicious-client](/docs/testing/tinylicious)).
+The fluid-framework package bundles a collection of Fluid Framework client libraries for easy use when paired with a corresponding service client package (for example, [@fluidframework/azure-client](../deployment/azure-fluid-relay) or [@fluidframework/tinylicious-client](../testing/tinylicious)).


Relative paths are preferred

Josmithr · 2025-01-23T22:27:54Z

docs/infra/api-markdown-documenter/render-api-documentation.mjs

+			[ApiItemKind.Model]: HierarchyKind.Document,
+			[ApiItemKind.Namespace]: HierarchyKind.Folder,
+			[ApiItemKind.Package]: HierarchyKind.Folder,


These values are the defaults for their respective types, but since we override document naming policy for them, seems reasonable to add them here explicitly to make the relationship clear.

alexvy86

I did what I could looking at the lockfile but very hard to review in detail. The rest looks good 👍 .

…archy-fixes

Josmithr · 2025-01-24T00:08:52Z

I did what I could looking at the lockfile but very hard to review in detail. The rest looks good 👍 .

@alexvy86 I hadn't even noticed the churn there. I need to do a better job of remembering to check the lockfile changes in my own PRs...

Did we recently update our lockfile versions elsewhere in the repo? These changes bumped the version from 6 to 9. I notice that the root lockfile is already on 9. Did we forget to update docs in some previous upgrade pass?

github-actions · 2025-01-24T00:15:36Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> [email protected] ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> [email protected] serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  169324 links
    1609 destination URLs
    1841 URLs ignored
       0 warnings
       0 errors

alexvy86 · 2025-01-24T00:17:59Z

Did we recently update our lockfile versions elsewhere in the repo? These changes bumped the version from 6 to 9. I notice that the root lockfile is already on 9. Did we forget to update docs in some previous upgrade pass?

Yeah, since #23318 the whole repo is on pnpm 9 now which comes with the lockfile update. Seems like we missed updating the lockfile for docs in that PR though.

Josmithr added 30 commits December 18, 2024 23:35

WIP

db9d9f1

chore: Add DeepRequired utility type

f80e4a6

chore: Type aliases and helper functions

ec1242f

[WIP]

410049c

style: Prettier

9d3ecb2

WIP

b8c8f83

More WIP

a67cf98

docs: Fix comments

964e4bf

fix: Correct handling of entry-points

600591a

fix: Types

571c170

refactor: Rename interface

63f253d

fix: End-to-end tests

824c7f0

fix: Config generation

cf91dc5

refactor: Rename types

3019028

refactor: Rename file

dad5814

fix: Restore support for document hierarchy for packages

81994f4

fix: Test configs

214ae3b

fix(test): Fix configurations

9786a34

refactor: Move function

8bce322

test: Remove invalid test case

fda21fa

fix: Document and folder naming

3071431

Merge branch 'main' into api-markdown-documenter/hierarchy-config

60f6e74

Merge branch 'main' into api-markdown-documenter/hierarchy-config

3e67819

Merge branch 'main' into api-markdown-documenter/hierarchy-config

e58de30

Merge branch 'main' into api-markdown-documenter/hierarchy-config

ef12ea3

Merge branch 'main' into api-markdown-documenter/hierarchy-config

7206e37

Merge branch 'main' into api-markdown-documenter/hierarchy-config

289c9eb

docs: Fix comment

e4f184c

refactor: Remove unneeded type alias

25162b5

docs: Remove obsolete TODO

92ecd59

Josmithr added 2 commits January 8, 2025 01:25

refactor: Further simplify hierarchy setup

05e70b6

build(docs): Update API docs build

f840b8e

github-actions bot added area: website public api change Changes to a public API base: main PRs targeted against main branch labels Jan 8, 2025

Josmithr added 2 commits January 23, 2025 01:01

Merge branch 'main' into docs/update-api-markdown-documenter-for-hier…

91e289d

…archy-fixes

fix: Import

02bc600

github-actions bot removed the public api change Changes to a public API label Jan 23, 2025

Josmithr added 6 commits January 23, 2025 01:03

revert: Unwanted change

480fe29

remove: Duplicated file

cf59b6f

fix: Local API docs sidebar config

fc48322

refactor: Update config

38376ee

Merge branch 'main' into docs/update-api-markdown-documenter-for-hier…

79dddbf

…archy-fixes

build: Update dep

a73d734

Josmithr commented Jan 23, 2025

View reviewed changes

docs/infra/api-markdown-documenter/render-api-documentation.mjs Show resolved Hide resolved

Josmithr commented Jan 23, 2025

View reviewed changes

docs: Update links

663a9e2

Josmithr marked this pull request as ready for review January 23, 2025 19:42

Josmithr requested review from alexvy86 and a team January 23, 2025 19:42

Josmithr commented Jan 23, 2025

View reviewed changes

alexvy86 approved these changes Jan 24, 2025

View reviewed changes

Merge branch 'main' into docs/update-api-markdown-documenter-for-hier…

a217ac1

…archy-fixes

Josmithr merged commit 6076f48 into microsoft:main Jan 24, 2025
27 checks passed

Josmithr deleted the docs/update-api-markdown-documenter-for-hierarchy-fixes branch January 24, 2025 00:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build(docs): Update api-markdown-documenter and utilize new hierarchy options #23504

build(docs): Update api-markdown-documenter and utilize new hierarchy options #23504

Josmithr commented Jan 8, 2025 •

edited by azure-boards bot

Loading

Josmithr Jan 23, 2025

Josmithr Jan 23, 2025

Josmithr Jan 23, 2025

Josmithr Jan 23, 2025

alexvy86 left a comment

Josmithr commented Jan 24, 2025

github-actions bot commented Jan 24, 2025

alexvy86 commented Jan 24, 2025

build(docs): Update api-markdown-documenter and utilize new hierarchy options #23504

build(docs): Update api-markdown-documenter and utilize new hierarchy options #23504

Conversation

Josmithr commented Jan 8, 2025 • edited by azure-boards bot Loading

Josmithr Jan 23, 2025

Choose a reason for hiding this comment

Josmithr Jan 23, 2025

Choose a reason for hiding this comment

Josmithr Jan 23, 2025

Choose a reason for hiding this comment

Josmithr Jan 23, 2025

Choose a reason for hiding this comment

alexvy86 left a comment

Choose a reason for hiding this comment

Josmithr commented Jan 24, 2025

github-actions bot commented Jan 24, 2025

linkcheck output

alexvy86 commented Jan 24, 2025

Josmithr commented Jan 8, 2025 •

edited by azure-boards bot

Loading