chore: replatform docs site to Astro + Starlight #7012
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
serhalp
force-pushed
the
chore/port-docs-site-to-astro
branch
from
4140021 to
2b9ddfd
Compare
serhalp
commented
Jan 22, 2025
Comment on lines
-6
to
-7
| # Netlify CLI command reference | ||
|
|
There was a problem hiding this comment.
Starlight uses the title front the frontmatter as the h1
serhalp
commented
Jan 22, 2025
Comment on lines
-7
to
-10
| [build.environment] | ||
| # cannot use node 18, as we use x0 which uses webpack 4 | ||
| NODE_VERSION = "16" | ||
| AWS_LAMBDA_JS_RUNTIME = "nodejs16.x" |
There was a problem hiding this comment.
oh look, the point of the PR 😁
serhalp
commented
Jan 22, 2025
serhalp
commented
Jan 22, 2025
Comment on lines
+5
to
+15
| ## Architecture | ||
|
|
||
| All the command reference pages and the list of commands are automatically generated from the CLI code. This is | ||
| automatically inserted into the existing, committed, semi-manually-written pages in `../docs/`. Here's how the flow | ||
| works: | ||
|
|
||
| 1. The `docs.js` script replaces the content between the auto-generation marker comments in the files in `../docs/`; the | ||
| rest you can update manually. | ||
| 2. The `sync.js` script copies these over to this Astro Starlight site, into `src/content/docs/`. It may also perform | ||
| some minor transformations. | ||
| 3. From there, it's any old Astro/Starlight docs site, as documented. |
There was a problem hiding this comment.
😅 This doesn't seem that complex but it took me a lot of trial-and-error and poking around to understand the whole flow. I hope this documentation is clear for the next person.
serhalp
commented
Jan 22, 2025
| lastmod: new Date(), | ||
| }), | ||
| starlight({ | ||
| credits: true, |
There was a problem hiding this comment.
They're our partner, so seemed like a good idea
serhalp
commented
Jan 22, 2025
| credits: true, | ||
| title: 'Netlify CLI command reference', | ||
| description: 'Full command reference for the Netlify CLI', | ||
| social: { |
There was a problem hiding this comment.
TODO we could add more socials here
There was a problem hiding this comment.
added youtube, github, twitter, bluesky (also found instagram and linkedin but feels weird here)
serhalp
commented
Jan 22, 2025
serhalp
commented
Jan 22, 2025
Comment on lines
+49
to
+61
| tag: 'script', | ||
| attrs: { | ||
| async: true, | ||
| src: 'https://www.googletagmanager.com/gtag/js?id=G-X2FMMZSSS9', | ||
| }, | ||
| }, | ||
| { | ||
| tag: 'script', | ||
| content: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': | ||
| new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], | ||
| j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= | ||
| 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); | ||
| })(window,document,'script','dataLayer','GTM-NMKKF2M');`, |
There was a problem hiding this comment.
copied these as-is from the existing site layout
serhalp
commented
Jan 22, 2025
Comment on lines
+100
to
+101
| label: 'Commands', | ||
| autogenerate: { directory: 'commands' }, |
There was a problem hiding this comment.
🤩 I was so happy to find this. So easy.
serhalp
commented
Jan 22, 2025
Comment on lines
-28
to
-52
| "@compositor/x0": "6.0.7", | ||
| "@rebass/markdown": "1.0.0", | ||
| "@rebass/mdx": "1.0.0", | ||
| "algoliasearch": "4.24.0", | ||
| "lodash.sortby": "4.7.0", | ||
| "prop-types": "15.8.1", | ||
| "react": "16.14.0", | ||
| "react-dom": "16.14.0", | ||
| "react-helmet": "6.1.0", | ||
| "react-instantsearch-dom": "6.40.4", | ||
| "react-router-dom": "4.3.1", | ||
| "react-emotion": "9.2.12", | ||
| "rebass": "2.3.4", | ||
| "styled-components": "3.4.10", | ||
| "styled-system": "5.1.5" | ||
| }, | ||
| "devDependencies": { | ||
| "@astrojs/starlight": "^0.31.1", | ||
| "astro": "^5.1.5", | ||
| "markdown-magic": "2.6.1", | ||
| "npm-run-all2": "5.0.2", | ||
| "sane": "5.0.1", | ||
| "sharp": "^0.32.5", | ||
| "strip-ansi": "7.1.0" | ||
| }, | ||
| "overrides": { | ||
| "react": "$react", | ||
| "react-dom": "$react-dom" |
serhalp
force-pushed
the
chore/port-docs-site-to-astro
branch
from
2b9ddfd to
9f6b622
Compare
serhalp
commented
Jan 22, 2025
|
|
||
| export const copyDirRecursiveAsync = async (src, dest) => { | ||
| try { | ||
| fs.mkdir(dest, { recursive: true }) | ||
| await mkdir(dest, { recursive: true }) |
There was a problem hiding this comment.
lol I was trying not to fix other things but I saw a couple bugs here
serhalp
commented
Jan 22, 2025
serhalp
commented
Jan 22, 2025
Comment on lines
-361
to
-384
| const Sosumi = () => ( | ||
| <SosumiList> | ||
| <li> | ||
| <a href="https://www.netlify.com/trust-center/">Trust Center</a> | ||
| </li> | ||
| <li> | ||
| <a href="https://www.netlify.com/privacy/">Privacy</a> | ||
| </li> | ||
| <li> | ||
| <a href="https://www.netlify.com/security/">Security</a> | ||
| </li> | ||
| <li> | ||
| <a href="https://www.netlify.com/gdpr-ccpa/">GDPR/CCPA</a> | ||
| </li> | ||
| <li> | ||
| <a | ||
| href="mailto:[email protected]?subject=Abuse%20report&body=Please%20include%20the%20site%20URL%20and%20reason%20for%20your%20report%2C%20and%20we%20will%20reply%20promptly." | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| Abuse | ||
| </a> | ||
| </li> | ||
| </SosumiList> |
There was a problem hiding this comment.
Do we care about this? There's no such footer on the SDK docs site
serhalp
force-pushed
the
chore/port-docs-site-to-astro
branch
from
9f6b622 to
a8f601e
Compare
I tried to resist the temptation to fix other tech debt here (untyped JS, etc.).
serhalp
force-pushed
the
chore/port-docs-site-to-astro
branch
from
a8f601e to
40db384
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
While working on #7008 I discovered that the docs site uses old libraries that have been unmaintained for 7 years, and thus cannot be upgraded past node 16. Because the build step for these docs uses code from the core CLI, this in turn means the core CLI can't be upgraded to any dependencies that don't support node 16. (See also a bit more nuanced context here.)
So I deleted everything, created a new Astro + Starlight site, and pasted the content generation script and bare minimum over, and cribbed a bit of the Astro/Starlight setup from the Netlify SDK docs. 🤷🏼 Looks pretty good, it's fast, it's functional, it has built-in search without needing Algolia anymore, it has dark mode, it's branded, it has copy-to-clipboard, and it has syntax highlighting, pretty much all for free.
I tried to resist the temptation to fix other tech debt here (untyped JS, etc.).