From 4e0c701e42f6893cc30b14ceb3455236605abec5 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Thu, 18 May 2023 08:32:09 +0200 Subject: Create a starter template (#71) --- examples/basics/.gitignore | 21 +++++++++ examples/basics/.vscode/extensions.json | 4 ++ examples/basics/.vscode/launch.json | 11 +++++ examples/basics/README.md | 51 +++++++++++++++++++++ examples/basics/astro.config.mjs | 31 +++++++++++++ examples/basics/package.json | 17 +++++++ examples/basics/public/favicon.svg | 1 + examples/basics/src/assets/example-image.jpg | Bin 0 -> 21173 bytes examples/basics/src/content/config.ts | 8 ++++ examples/basics/src/content/docs/guides/example.md | 11 +++++ examples/basics/src/content/docs/index.md | 18 ++++++++ .../basics/src/content/docs/reference/example.md | 11 +++++ examples/basics/src/env.d.ts | 2 + examples/basics/tsconfig.json | 3 ++ pnpm-lock.yaml | 10 +--- 15 files changed, 191 insertions(+), 8 deletions(-) create mode 100644 examples/basics/.gitignore create mode 100644 examples/basics/.vscode/extensions.json create mode 100644 examples/basics/.vscode/launch.json create mode 100644 examples/basics/README.md create mode 100644 examples/basics/astro.config.mjs create mode 100644 examples/basics/package.json create mode 100644 examples/basics/public/favicon.svg create mode 100644 examples/basics/src/assets/example-image.jpg create mode 100644 examples/basics/src/content/config.ts create mode 100644 examples/basics/src/content/docs/guides/example.md create mode 100644 examples/basics/src/content/docs/index.md create mode 100644 examples/basics/src/content/docs/reference/example.md create mode 100644 examples/basics/src/env.d.ts create mode 100644 examples/basics/tsconfig.json diff --git a/examples/basics/.gitignore b/examples/basics/.gitignore new file mode 100644 index 00000000..6240da8b --- /dev/null +++ b/examples/basics/.gitignore @@ -0,0 +1,21 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store diff --git a/examples/basics/.vscode/extensions.json b/examples/basics/.vscode/extensions.json new file mode 100644 index 00000000..22a15055 --- /dev/null +++ b/examples/basics/.vscode/extensions.json @@ -0,0 +1,4 @@ +{ + "recommendations": ["astro-build.astro-vscode"], + "unwantedRecommendations": [] +} diff --git a/examples/basics/.vscode/launch.json b/examples/basics/.vscode/launch.json new file mode 100644 index 00000000..d6422097 --- /dev/null +++ b/examples/basics/.vscode/launch.json @@ -0,0 +1,11 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "command": "./node_modules/.bin/astro dev", + "name": "Development server", + "request": "launch", + "type": "node-terminal" + } + ] +} diff --git a/examples/basics/README.md b/examples/basics/README.md new file mode 100644 index 00000000..5739bcb5 --- /dev/null +++ b/examples/basics/README.md @@ -0,0 +1,51 @@ +# Starlight Starter Kit: Basics + +``` +npm create astro@latest -- --template starlight +``` + +[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics) +[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics) + +> πŸ§‘β€πŸš€ **Seasoned astronaut?** Delete this file. Have fun! + +## πŸš€ Project Structure + +Inside of your Astro + Starlight project, you'll see the following folders and files: + +``` +. +β”œβ”€β”€ astro.config.mjs +β”œβ”€β”€ package.json +β”œβ”€β”€ public/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ assets/ +β”‚ β”œβ”€β”€ content/ +β”‚ β”‚ β”œβ”€β”€ config.ts +β”‚ β”‚ └── docs/ +β”‚ └── env.d.ts +└── tsconfig.json +``` + +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. + +Images can be added to `src/assets/` and embedded in Markdown with a relative link. + +Static assets, like favicons, can be placed in the `public/` directory. + +## 🧞 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:3000` | +| `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 | + +## πŸ‘€ Want to learn more? + +Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat). diff --git a/examples/basics/astro.config.mjs b/examples/basics/astro.config.mjs new file mode 100644 index 00000000..b3e86d36 --- /dev/null +++ b/examples/basics/astro.config.mjs @@ -0,0 +1,31 @@ +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +// https://astro.build/config +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + social: { + github: 'https://github.com/withastro/starlight', + }, + sidebar: [ + { + label: 'Start Here', + items: [ + // Each item here is one entry in the navigation menu. + { label: 'Getting Started', link: '/' }, + ], + }, + { + label: 'Guides', + autogenerate: { directory: 'guides' }, + }, + { + label: 'Reference', + autogenerate: { directory: 'reference' }, + }, + ], + }), + ], +}); diff --git a/examples/basics/package.json b/examples/basics/package.json new file mode 100644 index 00000000..c5d7a3b9 --- /dev/null +++ b/examples/basics/package.json @@ -0,0 +1,17 @@ +{ + "name": "@example/starlight-basics", + "type": "module", + "version": "0.0.1", + "private": true, + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview", + "astro": "astro" + }, + "dependencies": { + "@astrojs/starlight": "^0.0.8", + "astro": "^2.4.1" + } +} diff --git a/examples/basics/public/favicon.svg b/examples/basics/public/favicon.svg new file mode 100644 index 00000000..cba5ac14 --- /dev/null +++ b/examples/basics/public/favicon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/examples/basics/src/assets/example-image.jpg b/examples/basics/src/assets/example-image.jpg new file mode 100644 index 00000000..ad32033f Binary files /dev/null and b/examples/basics/src/assets/example-image.jpg differ diff --git a/examples/basics/src/content/config.ts b/examples/basics/src/content/config.ts new file mode 100644 index 00000000..4cdd345e --- /dev/null +++ b/examples/basics/src/content/config.ts @@ -0,0 +1,8 @@ +import { defineCollection } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ + schema: docsSchema(), + }), +}; diff --git a/examples/basics/src/content/docs/guides/example.md b/examples/basics/src/content/docs/guides/example.md new file mode 100644 index 00000000..ebd0f3bc --- /dev/null +++ b/examples/basics/src/content/docs/guides/example.md @@ -0,0 +1,11 @@ +--- +title: Example Guide +description: A guide in my new Starlight docs site. +--- + +Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. +Writing a good guide requires thinking about what your users are trying to do. + +## Further reading + +- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the DiΓ‘taxis framework diff --git a/examples/basics/src/content/docs/index.md b/examples/basics/src/content/docs/index.md new file mode 100644 index 00000000..581a1b88 --- /dev/null +++ b/examples/basics/src/content/docs/index.md @@ -0,0 +1,18 @@ +--- +title: Welcome to Starlight +description: Get started building your docs site with Starlight. +--- + +Congrats on setting up a new Starlight project! + +![An example image welcoming new Starlight users with the Starlight logo](../../assets/example-image.jpg) + +## Next steps + +- Edit `src/content/docs/index.md` to see this page change. + +- Add Markdown or MDX files to `src/content/docs` to create new pages. + +- Edit your `sidebar` and other config in `astro.config.mjs`. + +- Learn more in [the Starlight Docs](https://starlight.astro.build/). diff --git a/examples/basics/src/content/docs/reference/example.md b/examples/basics/src/content/docs/reference/example.md new file mode 100644 index 00000000..ac8cfa8b --- /dev/null +++ b/examples/basics/src/content/docs/reference/example.md @@ -0,0 +1,11 @@ +--- +title: Example Reference +description: A reference page in my new Starlight docs site. +--- + +Reference pages are ideal for outlining how things work in terse and clear terms. +Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what your documenting. + +## Further reading + +- Read [about reference](https://diataxis.fr/reference/) in the DiΓ‘taxis framework diff --git a/examples/basics/src/env.d.ts b/examples/basics/src/env.d.ts new file mode 100644 index 00000000..4170bce9 --- /dev/null +++ b/examples/basics/src/env.d.ts @@ -0,0 +1,2 @@ +/// +/// diff --git a/examples/basics/tsconfig.json b/examples/basics/tsconfig.json new file mode 100644 index 00000000..77da9dd0 --- /dev/null +++ b/examples/basics/tsconfig.json @@ -0,0 +1,3 @@ +{ + "extends": "astro/tsconfigs/strict" +} \ No newline at end of file diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 35c0e7c0..4bf4f06a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -95,7 +95,7 @@ packages: engines: {node: '>=6.0.0'} dependencies: '@jridgewell/gen-mapping': 0.1.1 - '@jridgewell/trace-mapping': 0.3.17 + '@jridgewell/trace-mapping': 0.3.18 /@astrojs/compiler@1.4.1: resolution: {integrity: sha512-aXAxapNWZwGN41P+Am/ma/2kAzKOhMNaY6YuvLkUHFv+UZkmDHD6F0fE1sQA2Up0bLjgPQa1VQzoAaii5tZWaA==} @@ -829,7 +829,7 @@ packages: dependencies: '@jridgewell/set-array': 1.1.2 '@jridgewell/sourcemap-codec': 1.4.14 - '@jridgewell/trace-mapping': 0.3.17 + '@jridgewell/trace-mapping': 0.3.18 /@jridgewell/resolve-uri@3.1.0: resolution: {integrity: sha512-F2msla3tad+Mfht5cJq7LSXcdudKTWCVYUgw6pLFOOHSTtZlj6SWNYAp+AhuqLmWdBO2X5hPrLcu8cVP8fy28w==} @@ -842,12 +842,6 @@ packages: /@jridgewell/sourcemap-codec@1.4.14: resolution: {integrity: sha512-XPSJHWmi394fuUuzDnGz1wiKqWfo1yXecHQMRf2l6hztTO+nPru658AyDngaBe7isIxEkRsPR3FZh+s7iVa4Uw==} - /@jridgewell/trace-mapping@0.3.17: - resolution: {integrity: sha512-MCNzAp77qzKca9+W/+I0+sEpaUnZoeasnghNeVc41VZCEKaCH73Vq3BZZ/SzWIgrqE4H4ceI+p+b6C0mHf9T4g==} - dependencies: - '@jridgewell/resolve-uri': 3.1.0 - '@jridgewell/sourcemap-codec': 1.4.14 - /@jridgewell/trace-mapping@0.3.18: resolution: {integrity: sha512-w+niJYzMHdd7USdiH2U6869nqhD2nbfZXND5Yp93qIbEmnDNk7PD48o+YchRVpzMU7M6jVCbenTR7PA1FLQ9pA==} dependencies: -- cgit