Skip to content

Latest commit

 

History

History
114 lines (91 loc) · 4.39 KB

README.md

File metadata and controls

114 lines (91 loc) · 4.39 KB

Starlight Starter Kit: Basics

Built with Starlight

The documentation site for this project is built with Astro Starlight and hosted on GitHub Pages. Here are the steps to replicate this process.


🏁 | Create New Project

  1. Use the command below to start the wizard workflow. Follow interactive steps to setup the default project.

    npm create astro@latest -- --template starlight

🚀 | Project Structure

  1. Inside of your Astro + Starlight project, you'll see the following folders and files:

    .
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   │   └── config.ts
│   └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

  2. Starlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on its file name.

  3. Images can be added to src/assets/ and embedded in Markdown with a relative link.

  4. Static assets, like favicons, can be placed in the public/ directory.


🧰 | Customize Project

  1. Astro collects telemetry by default - use the command below to opt-out.

    npm run astro telemetry disable
...
Astro is no longer collecting anonymous usage data.

  2. Preview the site locally:

    cd docs
npm run dev
...
Local http://localhost:4321

  3. Build & preview static site: (builds in dist/)

    cd docs
npm run build
npm run preview
...
Local http://localhost:4321

  4. Modify the default configuration as required (see Docs).

    1. Astro has type-safe frontmatter. Use it in content pages.
    2. Starlight builds on content collections. Configure it in src/content/config.ts
    3. Site homepage is at src/content/docs/index.md
    4. Use admonitions or asides - for {note, tip, caution, danger}
    5. Use code highlighting with
      • expressive code text markers (show adds, deletes)
      • frames, tabs and titles for code window
    6. Use built-in components or create custom ones
      • built-in tabs, icons
      • built-in cards, link-cards
      • built-in "code import" capability
    7. Customize CSS by
      • adding file in src/ e.g., src/styles/custom.css.
      • referencing it in astro.config.mjs "integrations"
      • using Tailwind CSS support (with related integration)
    8. Customize Theme by
      • Changing values for Theming
      • Copying the values into a src/styles/custom.css file
      • Applying that as your default in astro.config.mjs
    9. Make yourself a logo with Bing Create
      • Create different logos for light and dark if needed
      • named assets under src/assets
      • scoped properties under starlight config

🧞 | More Commands

All commands are run from the root of the project, from a terminal:

Command Action
npm install Installs dependencies
npm run dev Starts local dev server at localhost:4321
npm run build Build your production site to ./dist/
npm run preview Preview your build locally, before deploying
npm run astro ... Run CLI commands like astro add, astro check
npm run astro -- --help Get help using the Astro CLI
npx @astrojs/upgrade Upgrade to latest Astro release regularly

👀 | Learn More

  1. Check out Starlight’s docs
  2. Read the Astro documentation, or
  3. Jump into the Astro Discord server.