feat(vitepress): updates site to use vitepress #971

0xpatrickdev · 2024-02-09T04:43:08Z

closes: #972
refs: #609

Summary

vitepress is the successor to vuepress (maintence mode). I looked into it yesterday in search of a better site search and came to realize the apis are very similar.
uses default theme from vitepress, with agoric branded colors
search now powered by minisearch, client-size full-text search. Previously, we were only searching document titles.

To Do

…h strings

to do: (!) Found dead link /guides/agoric-cli/README in file guides/getting-started/deploying.md (!) Found dead link /ertp/api/index in file guides/ertp/issuers-and-mints.md (!) Found dead link http://localhost:3000 in file guides/dapps/index.md (!) Found dead link /guides/wallet/README in file guides/coreeval/permissions.md (!) Found dead link /ertp/api/index in file guides/ertp/purses-and-payments.md (!) Found dead link ./../../glossary/README in file guides/js-programming/eventual-send.md (!) Found dead link ./../zoe/actual-contracts/index in file guides/integration/name-services.md (!) Found dead link ./../zoe/actual-contracts/index in file guides/integration/name-services.md (x2) (!) Found dead link /repl/timerServices in file guides/js-programming/notifiers.md (!) Found dead link ./../../glossary/README in file guides/js-programming/notifiers.md (!) Found dead link /zoe/guide/contracts/index in file guides/zoe/index.md (!) Found dead link /zoe/guide/contracts/constantProductAMM in file guides/zoe/index.md + external redirects + subpath redirects

cloudflare-workers-and-pages · 2024-02-09T20:52:16Z

Deploying documentation with Cloudflare Pages

Latest commit:	`b1eed18`
Status:	✅ Deploy successful!
Preview URL:	https://65175600.documentation-7tp.pages.dev
Branch Preview URL:	https://pc-vitepress.documentation-7tp.pages.dev

View logs

0xpatrickdev · 2024-02-10T01:06:45Z

main/.vitepress/components/Zoe-Version.vue

+<template>
+<div class="zoe-version">
+    Zoe {{ zoeVersion }}. Last updated
+    {{ zoeDocsUpdated }}.


For the future, do we we get value out of this? It's hardcoded to August 25, 2022. VuePress had a lastUpdatedAt plugin for individual .md's that is also available in VitePress (and active on our site)

I think it's supposed to indicate when the zoe code was last updated. It might be nice to say what version of code we're documenting.

But yeah... currently, this is just noise.

0xpatrickdev · 2024-02-13T01:31:41Z

Deployed something here for the interim: https://65cac5889558bd35423c70e1--beautiful-lolly-46c6b2.netlify.app/

I used the output of yarn docs:build + _redirects. Netlfiy and Cloudflare seem to have the same _redirects structure.

0xpatrickdev · 2024-02-13T15:02:58Z

also fixes #609 ?

I did not tackle eslint in this, but can update the PR body with refs. #965 seems like it also contributes to #609

dckc · 2024-02-19T18:20:01Z

horizontal margins look goofy... including a scrollbar. important

dckc

found a couple important things

dckc · 2024-02-19T18:23:23Z

package.json

-    "docs:build-cf": "NODE_OPTIONS=--openssl-legacy-provider vuepress build main && cp _redirects main/.vuepress/dist/",
-    "docs:build-root": "NODE_OPTIONS=--openssl-legacy-provider yarn docs:build && yarn docs:re-root && cp _redirects main/.vuepress/dist-root/",
-    "docs:re-root": "cd main && mkdir -p .vuepress/dist-root/ && cp -rp .vuepress/dist/ .vuepress/dist-root/documentation/",
-    "check-links": "NODE_OPTIONS=--openssl-legacy-provider vuepress check-md main",


what happened to check-links?

important

check-links is noted in CONTRIBUTING.md. I wonder if this PR is consistent with the rest of the stuff in there.

check-links logic is still there - it's natively part of of vitepress via ignoreDeadLinks, configured here, and will run during yarn docs:build.

Example failure:

yarn docs:build yarn run v1.22.5 $ NODE_OPTIONS=--openssl-legacy-provider vitepress build main vitepress v1.0.0-rc.42 (!) Found dead link ./../js-fprogramming/index in file guides/zoe/contract-upgrade.md If this is expected, you can disable this check via config. Refer: https://vitepress.dev/reference/site-config#ignoredeadlinks ✖ building client + server bundles... build error: Error: [vitepress] 1 dead link(s) found.

CONTRIBUTING.md changes are on the radar, added two more commits 6320811, 5594baa that make adjustments.

- simplifies CI, which currently looks in main/.vitepress/dist or main/.vuepress/dist

dckc · 2024-02-20T18:46:14Z

main/guides/zoe/contract-basics.md

-objects that last across upgrades ([durable objects](./contract-upgrade.md#durability)) later.
+objects that last across upgrades ([durable objects](./contract-upgrade#durability)) later.


odd... links don't go to xyz.md anymore?

They do, but the the extensions are now optional so I chose to remove them for simplicity.

Hm. simplicity vs. consistency...

CONTRIBUTING still says

Next, your Markdown links should be to the .md Markdown files ...

So unless we aim to change the shop norm, I prefer consistency. (not critical)

The wording of that sentence is a bit confusing to me. Updated here 37b292d

0xpatrickdev · 2024-02-29T17:44:48Z

main/.vitepress/enhanceApp.js

+// XXX
+// vitepress does not seem to expose the vue router directly, so we'll
+// have to refactor this. some redirects are working in themeConfig/rewrites.js
+


@gibson042 when you have some time, could you take a look at this PR and help me understand #882 and #888 better?

For #888, external redirects, is it sufficient to use _redirects and handle this outside the application? Cloudflare Pages Redirects

For #882, I'm not sure I understand the motivation enough to tell if the issue is still persistent with vitepress.

If you are looking for hosted preview URL, try this: https://0ebcfb0d.documentation-7tp.pages.dev/

Let's check #888 first:

https://0ebcfb0d.documentation-7tp.pages.dev/guides/js-programming/ses/lockdown.html is good ✔

https://0ebcfb0d.documentation-7tp.pages.dev/zoe/guide/contracts/covered-call.html is not ✘

I think the latter can be fixed with greedy matching, e.g.

/zoe/guide /guides/zoe/ /zoe/guide/* /guides/zoe/:splat

So probably we just want to map redirects from main/.vuepress/enhanceApp.js into _redirects:

Each prefix-style entry in the former should become two entries in the latter as above.

Each leaf-page entry in the former should become two entries in the latter to the same destination, one with a source ending in ".html" and the other not (e.g. https://0ebcfb0d.documentation-7tp.pages.dev/wallet-api.html and https://0ebcfb0d.documentation-7tp.pages.dev/wallet-api should both work).

For proper behavior, at least all non-external redirects should use status code 301 (Moved Permanently).

As for #882, it looks like we do need to carry the kludge forward (or find a way to fix things upstream). Observe how clicking either of the following links in the foreground (e.g., not a background tab) scrolls away from the in-page anchor to the top of page:

https://0ebcfb0d.documentation-7tp.pages.dev/reference/zoe-api/zoe-data-types.html#keywordrecord

https://0ebcfb0d.documentation-7tp.pages.dev/reference/zoe-api/zoe-data-types.html#amountkeywordrecord

But something is different, because even manual application doesn't appear to be correcting the issue.

Thanks @gibson042 !

For #888, it turns out the build you were looking at already had the custom scroll logic in place. In 5983738 I removed the logic, and scroll to anchor on initial page load seems to work fine (as a nit, it could scroll up a bit more, but it seems to be fine from my POV)

For #882 (redirects), I followed your suggestion in c69ed8a:

I am not sure if we need something like: /ertp/guide/ /guides/ertp/ in addition to /ertp/guide /guides/ertp/, but it doesn't seem to cause any harm. /* /:splat seems to cover the covered-call example you shared. Verified on this deploy url.

Edit:
Tested these links:
https://65f33b9537ffb20c818e3c7a--visionary-marzipan-3cd6de.netlify.app/reference/zoe-api/zoe-data-types#keywordrecord
https://65f33b9537ffb20c818e3c7a--visionary-marzipan-3cd6de.netlify.app/reference/zoe-api/zoe-data-types.html#keywordrecord

It does not seem we have an #amountkeywordrecord anchor on the page, so excluding that from my test cases.

https://65f33b9537ffb20c818e3c7a--visionary-marzipan-3cd6de.netlify.app/zoe/guide/contracts/covered-call
https://65f33b9537ffb20c818e3c7a--visionary-marzipan-3cd6de.netlify.app/zoe/guide/contracts/covered-call.html

- removes code added in #882 that aimed to fix anchor tag linking on initial page loads as it no longer seems necessary with vitepress

- restores current styles on docs.agoric.com, ensuring users do not need to horizontally scroll

- ports vuepress redirects (client side) to cloudflare _redirects - see comment: #971 (comment)

main/.vitepress/config.mjs

dckc

Let's go for it.

I'm somewhat unsure that I reviewed this closely enough to find all possible regressions, but the benefit of fulltext search and a maintained platform are sufficient that it's worth the risk. If we find regressions, we can address them in due course.

0xpatrickdev · 2024-03-14T19:42:34Z

To merge this, we need to change the Build Output Directory in the cloudflare dash from /main/.vuepress/dist to /dist. The yarn docs:build-cf command (which copies _redirects into /dist) should stay the same.

We could make this deploy from /main/.vuepress/dist, but seems worthwhile to use a more generic /dist.

- there are probably add'l duplicates that can be removed - seems the /* /:splat pattern should cover many of individual page links

0xpatrickdev added 18 commits February 8, 2024 19:51

feat: vuepress -> vitepress

9b64660

feat(styles): default vitepress theme

dbc3632

feat(vitepress): snippets path resolution

37ac6cb

feat(vitepress): rename README.md -> index.md

9844392

feat(vitepress): update sidebar key names

6e1000a

refactor(vitepress): sidebar use text and link objects instead of pat…

bedd10a

…h strings

refactor(vitepress): set sidebar collapsed true

8deb74f

refactor(vitepress): register components

badf655

refactor(vitepress): agoric brand theme

41fdeeb

fix: index.md has extra double quote

f748428

feat(vitepress): add docs:preview script

c588227

refactor(vitepress): move public to srcDir (main)

d2cabba

refactor: light/dark mode friendly logo

388fe30

refactor(vitepress): support existing stylus styles

f5f9406

feat(vitepress): enable minisearch

e06b4f8

refactor(vitepress): themeConfig.zoeVersion in Zoe-Version.vue undefined

0be2346

fix(vitepress): ci jobs

135131d

0xpatrickdev added 3 commits February 9, 2024 18:28

chore(vitepress): update docs

5eb809a

refactor(vitepress): ensure all links are active

c1ee29f

refactor(vitepress): lastUpdatedAt configuration

6f4c403

0xpatrickdev commented Feb 10, 2024

View reviewed changes

0xpatrickdev force-pushed the pc/vitepress branch from cd45bad to de16bdb Compare February 10, 2024 01:09

0xpatrickdev added 2 commits February 9, 2024 20:13

feat: add sitemap

e963c1f

refactor: remove extraneous .html extension

c283f04

0xpatrickdev force-pushed the pc/vitepress branch from de16bdb to c283f04 Compare February 10, 2024 01:15

0xpatrickdev requested review from gibson042 and removed request for gibson042 February 10, 2024 01:18

refactor: drop extraneous .md

f7a6c5a

dckc mentioned this pull request Feb 19, 2024

build tool doesn't grok github style yaml header dckc/madmode-blog#148

Closed

dckc requested changes Feb 19, 2024

View reviewed changes

0xpatrickdev added 3 commits February 20, 2024 13:10

docs: update CONTRIBUTING.md

6320811

Merge branch 'main' into pc/vitepress

6ad99d9

chore(ci): set outDir to /dist in project root

5594baa

- simplifies CI, which currently looks in main/.vitepress/dist or main/.vuepress/dist

dckc reviewed Feb 20, 2024

View reviewed changes

docs: internal links should not include .md file extensions

37b292d

0xpatrickdev commented Feb 29, 2024

View reviewed changes

dckc assigned 0xpatrickdev Mar 11, 2024

dckc mentioned this pull request Mar 14, 2024

restore redirects from vitepress transition #991

Closed

1 task

0xpatrickdev added 4 commits March 14, 2024 13:23

Merge branch 'main' into pc/vitepress

4a6158c

fix: remove custom scroll restoration logic

5983738

- removes code added in #882 that aimed to fix anchor tag linking on initial page loads as it no longer seems necessary with vitepress

fix: mobile styles

5358d21

- restores current styles on docs.agoric.com, ensuring users do not need to horizontally scroll

fix(vitepress): restore existing redirects logic

c69ed8a

- ports vuepress redirects (client side) to cloudflare _redirects - see comment: #971 (comment)

0xpatrickdev requested a review from dckc March 14, 2024 18:11

0xpatrickdev commented Mar 14, 2024

View reviewed changes

main/.vitepress/config.mjs Show resolved Hide resolved

fixup! fix(vitepress): restore existing redirects logic

df40be4

dckc approved these changes Mar 14, 2024

View reviewed changes

0xpatrickdev enabled auto-merge March 14, 2024 20:04

refactor(redirects): alphabetize and remove duplicates

b1eed18

- there are probably add'l duplicates that can be removed - seems the /* /:splat pattern should cover many of individual page links

0xpatrickdev force-pushed the pc/vitepress branch from cc37f6d to b1eed18 Compare March 14, 2024 20:12

0xpatrickdev merged commit 1c9e995 into main Mar 14, 2024
4 checks passed

0xpatrickdev deleted the pc/vitepress branch March 14, 2024 20:24

This was referenced Mar 19, 2024

Reference missing from left nav bar #1005

Closed

"edit this page" links gone #1003

Closed

checking links fails to account for section anchors / hashes #1011

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(vitepress): updates site to use vitepress #971

feat(vitepress): updates site to use vitepress #971

0xpatrickdev commented Feb 9, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Feb 9, 2024 •

edited

Loading

0xpatrickdev Feb 10, 2024

dckc Feb 20, 2024

0xpatrickdev commented Feb 13, 2024

0xpatrickdev commented Feb 13, 2024

dckc commented Feb 19, 2024 •

edited

Loading

dckc left a comment

dckc Feb 19, 2024

dckc Feb 19, 2024

0xpatrickdev Feb 20, 2024 •

edited

Loading

dckc Feb 20, 2024

0xpatrickdev Feb 20, 2024

dckc Feb 20, 2024

0xpatrickdev Feb 29, 2024

0xpatrickdev Feb 29, 2024

gibson042 Feb 29, 2024

0xpatrickdev Mar 14, 2024 •

edited

Loading

dckc left a comment

0xpatrickdev commented Mar 14, 2024 •

edited

Loading

		objects that last across upgrades ([durable objects](./contract-upgrade.md#durability)) later.
		objects that last across upgrades ([durable objects](./contract-upgrade#durability)) later.

feat(vitepress): updates site to use vitepress #971

feat(vitepress): updates site to use vitepress #971

Conversation

0xpatrickdev commented Feb 9, 2024 • edited Loading

Summary

To Do

cloudflare-workers-and-pages bot commented Feb 9, 2024 • edited Loading

Deploying documentation with Cloudflare Pages

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xpatrickdev commented Feb 13, 2024

0xpatrickdev commented Feb 13, 2024

dckc commented Feb 19, 2024 • edited Loading

dckc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xpatrickdev Feb 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xpatrickdev Mar 14, 2024 • edited Loading

Choose a reason for hiding this comment

dckc left a comment

Choose a reason for hiding this comment

0xpatrickdev commented Mar 14, 2024 • edited Loading

0xpatrickdev commented Feb 9, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Feb 9, 2024 •

edited

Loading

dckc commented Feb 19, 2024 •

edited

Loading

0xpatrickdev Feb 20, 2024 •

edited

Loading

0xpatrickdev Mar 14, 2024 •

edited

Loading

0xpatrickdev commented Mar 14, 2024 •

edited

Loading