Skip to content

Overhaul getting started guide#1026

Merged
delucis merged 4 commits intomainfrom
chris/getting-started
Nov 2, 2023
Merged

Overhaul getting started guide#1026
delucis merged 4 commits intomainfrom
chris/getting-started

Conversation

@delucis
Copy link
Copy Markdown
Member

@delucis delucis commented Nov 2, 2023

What kind of changes does this PR include?

  • Changes or translations of Starlight docs site content

Description

  • This PR overhauls the getting started page in docs.
  • Main aims:
    • Mention how to start the dev server after creating your project (feedback from this video of someone working through the page).
    • Streamline some of the content and give readers more options to jump into the rest of the docs.
    • More clearly separate the “Getting Started” steps from the other things we’ve shoehorned into this page (“Updating” and “Troubleshooting”).

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Nov 2, 2023 •
edited
Loading

⚠️ No Changeset found

Latest commit: 2b864ab

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@netlify
Copy link
Copy Markdown

netlify bot commented Nov 2, 2023 •
edited
Loading

✅ Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit 2b864ab
🔍 Latest deploy log https://app.netlify.com/sites/astro-starlight/deploys/65441905f3c7790008cb6659
😎 Deploy Preview https://deploy-preview-1026--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse		 1 paths audited
Performance: 100 (no change from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 92 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

@github-actions github-actions bot added the 📚 docs Documentation website changes label Nov 2, 2023
@astrobot-houston
Copy link
Copy Markdown
Contributor

astrobot-houston commented Nov 2, 2023 •
edited
Loading

size-limit report 📦

Path Size
/index.html 5.13 KB (0%)
/_astro/*.js 19.27 KB (0%)
/_astro/*.css 9.72 KB (0%)

@delucis delucis requested a review from sarah11918 November 2, 2023 13:12
sarah11918
sarah11918 reviewed Nov 2, 2023
View reviewed changes
Copy link
Copy Markdown
Member

@sarah11918 sarah11918 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks fabulous, @delucis! Especially love the Next Steps section!

Just a few thoughts going though, but this is wonderful!

docs/src/content/docs/getting-started.mdx
## Deploying your Starlight website

Once you have created and customized your Starlight website, you can deploy it to a web server or hosting platform of your choice including Netlify, Vercel, GitHub Pages and many more.
### Next steps
Copy link
Copy Markdown
Member

@sarah11918 sarah11918 Nov 2, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I LOVE these next steps!

@delucis @sarah11918
Add manual setup link
addba89 
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
HiDeoo
HiDeoo reviewed Nov 2, 2023
View reviewed changes
Copy link
Copy Markdown
Member

@HiDeoo HiDeoo left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow, this is really great. So many improvements all over the place and I love the dev server/next steps sections.

The only thing that I've always found a bit confusing (at least for me as a non-native reader with my definition of theme and we may have already discussed this) is not really related to the changes, but maybe it's more obvious now, is the fact that we say "Starlight is a full-featured documentation theme" and later "Starlight is an Astro integration". Not sure if anything should be done about it, but I thought I'd mention it.

@delucis
Copy link
Copy Markdown
Member Author

delucis commented Nov 2, 2023

we say "Starlight is a full-featured documentation theme" and later "Starlight is an Astro integration"

Yeah, I think this is part of the issue for ourselves of answering “What is Starlight?” 😅

I’d argue that “theme” and “integration” are not mutually exclusive and in both cases we’re drawing attention to the “built on Astro” aspect, which is important because understanding that is really helpful in knowing what else you can do with Starlight. But I still agree the messaging isn’t perfect there. (And there is also the element that you can also use Starlight without really caring about Astro, at least for basic usage.)

I do think we can improve this in the first paragraph though, will make a suggestion.

delucis
delucis commented Nov 2, 2023
View reviewed changes
@delucis delucis merged commit 0100298 into main Nov 2, 2023
@delucis delucis deleted the chris/getting-started branch November 2, 2023 22:30
@HiDeoo HiDeoo mentioned this pull request Nov 3, 2023
Merged
HiDeoo added a commit to HiDeoo/starlight that referenced this pull request Nov 5, 2023
@HiDeoo
Merge branch 'main' into hd-plugins
6da9b51 
* main: (103 commits)
  i18n(fr): update `guides/sidebar.mdx` (withastro#1033)
  i18n(fr): update `reference/configuration.mdx` (withastro#1034)
  i18n(fr): update `reference/frontmatter.md` (withastro#1035)
  Fix docs component details (withastro#1031)
  Overhaul getting started guide (withastro#1026)
  i18n(zh-cn): Update sidebar.mdx & configuration.mdx (withastro#1022)
  i18n(es): Update `configuration` & `sidebar` (withastro#1029)
  [ci] format
  i18n(zh-cn): Update frontmatter.md (withastro#1020)
  i18n(zh-cn): Update overrides.md (withastro#1021)
  i18n(zh-cn): Update i18n.mdx (withastro#1019)
  fix(docs-i18n-tracker): update `translations` import (withastro#1025)
  [ci] format
  i18n(zh-cn): Update css-and-tailwind.mdx (withastro#1018)
  [ci] format
  i18n(zh-cn): Update authoring-content.md (withastro#1016)
  i18n(ko-KR): update `configuration.mdx` (withastro#1015)
  i18n(ko-KR): update `sidebar.mdx` (withastro#1014)
  i18n(ko-KR): update `i18n.mdx` (withastro#1013)
  [ci] format
  ...
@vasfvitor vasfvitor mentioned this pull request Nov 10, 2023
Merged
1 task
@leovoon leovoon mentioned this pull request Nov 29, 2023
Merged
@morinokami morinokami mentioned this pull request Dec 2, 2023
Merged
trueberryless added a commit to trueberryless/withastro-starlight that referenced this pull request Oct 14, 2024
@trueberryless
include changes from withastro#1026
b153a40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@HiDeoo HiDeoo HiDeoo left review comments

@sarah11918 sarah11918 sarah11918 left review comments

Assignees

No one assigned

Labels

📚 docs Documentation website changes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@delucis @astrobot-houston @HiDeoo @sarah11918