Skip to content

Commit de8a3cd

Browse files
moonclavedevmoonclavedev
committed
[readme] Initial Readme setup
1 parent 32421a5 commit de8a3cd

File tree

3 files changed

+124
-38
lines changed

3 files changed

+124
-38
lines changed

‎README.md‎

Lines changed: 122 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,141 @@
1-
# Starlight Starter Kit: Tailwind
1+
# <picture style="float:left; margin-right: 8px;"><source media="(prefers-color-scheme: dark)" srcset="./src/assets/aptos-logomark-dark.svg"><img src="./src/assets/aptos-logomark-light.svg" alt="Aptos logo" width="40" height="40"></picture> Aptos Docs
22

3-
[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
3+
This repository contains the source code for the official Aptos Developer Documentation, built using [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/).
44

5+
## Quick Start
6+
7+
```bash
8+
# Clone the repository
9+
git clone https://github.com/aptos-labs/aptos-docs.git
10+
cd aptos-docs
11+
12+
# Install dependencies
13+
pnpm install
14+
15+
# Set up environment variables
16+
cp .env.example .env
17+
18+
# Start the development server
19+
pnpm dev
520
```
6-
npm create astro@latest -- --template starlight/tailwind
21+
22+
Visit `http://localhost:4321` to see the documentation running locally.
23+
24+
## Editing Documentation
25+
26+
The main documentation content is located in the `src/content/docs/` directory:
27+
28+
- Content is organized in directories that match the URL structure
29+
- Files are written in Markdown MDX (`.mdx`) format
30+
- Each file begins with frontmatter (metadata between `---` delimiters)
31+
32+
Example frontmatter:
33+
34+
```yaml
35+
---
36+
title: Your Page Title
37+
description: A brief description of the page content
38+
---
739
```
840

9-
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/tailwind)
10-
[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/tailwind)
11-
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/tailwind)
12-
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Ftailwind&project-name=my-starlight-docs&repository-name=my-starlight-docs)
41+
For more resources on authoring content within this environment, see:
42+
43+
- [Authoring Content in Markdown](https://starlight.astro.build/guides/authoring-content/)
44+
- [Using Components](https://starlight.astro.build/components/using-components/)
1345

14-
> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
46+
With the development server running (`pnpm dev`), your changes will be reflected immediately.
1547

16-
## 🚀 Project Structure
48+
## Prerequisites
1749

18-
Inside of your Astro + Starlight project, you'll see the following folders and files:
50+
- **Node.js:** Version 22.x (specified in `.nvmrc`, use [nvm](https://github.com/nvm-sh/nvm))
51+
- **pnpm:** Version 10.2.0 or higher (`npm install -g pnpm`)
52+
- **Git:** For cloning the repository
53+
54+
## Key Features
55+
56+
- Multi-language support
57+
- Interactive components (GraphiQL editor, Testnet Faucet)
58+
- API Reference via OpenAPI specifications
59+
- Move Reference documentation
60+
- Search functionality (Algolia DocSearch)
61+
- Dynamic OG Images
62+
63+
## Common Commands
64+
65+
| Command | Description |
66+
| -------------- | ----------------------------- |
67+
| `pnpm dev` | Start the development server |
68+
| `pnpm build` | Build the site for production |
69+
| `pnpm preview` | Preview the production build |
70+
| `pnpm lint` | Check for linting issues |
71+
| `pnpm format` | Fix formatting issues |
72+
73+
## Environment Variables
74+
75+
Key environment variables:
76+
77+
| Variable | Type | Purpose | Required? |
78+
| ----------------------- | ------ | ------------------------------ | ------------------------------------ |
79+
| `GITHUB_TOKEN` | Secret | Fetching Move Reference docs | Only if `ENABLE_MOVE_REFERENCE=true` |
80+
| `ENABLE_API_REFERENCE` | Public | Build REST API reference pages | Optional (default: `false`) |
81+
| `ENABLE_MOVE_REFERENCE` | Public | Build Move Reference docs | Optional (default: `false`) |
82+
| Firebase Credentials | Public | Authentication features | Required for Faucet/Auth |
83+
| Algolia Credentials | Public | Documentation search | Optional |
84+
| `GTAG_ID` | Public | Google Analytics tracking | Optional |
85+
| `OG_IMAGES_SECRET` | Secret | Dynamic OG image generation | Recommended for Vercel |
86+
87+
## Project Structure
1988

2089
```
2190
.
22-
├── public/
91+
├── config/ # Global sidebar configuration helper
92+
├── patches/ # Patched npm dependencies
93+
├── public/ # Static assets
94+
├── scripts/ # Utility scripts (Migration & Middleware generation)
2395
├── src/
24-
│ ├── assets/
25-
│ ├── content/
26-
│ │ ├── docs/
27-
│ └── content.config.ts
28-
├── astro.config.mjs
29-
├── package.json
30-
├── tailwind.config.mjs
31-
└── tsconfig.json
96+
│ ├── assets/ # Site assets
97+
│ ├── components/ # Reusable components
98+
│ ├── config/ # Configuration helpers (i18n, docSearch, sidebar)
99+
│ ├── content/ # Content Collections
100+
│ │ ├── docs/ # Main documentation content
101+
│ │ ├── i18n/ # UI translations
102+
│ │ └── nav/ # Sidebar translations
103+
│ ├── integrations/ # Custom integrations
104+
│ ├── lib/ # Utility functions
105+
│ ├── loaders/ # Content Collection loaders
106+
│ ├── middlewares/ # Edge Middleware
107+
│ ├── pages/ # Astro pages
108+
│ ├── plugins/ # Remark/Rehype plugins
109+
│ ├── starlight-overrides/ # Overridden components
110+
│ ├── stores/ # State management
111+
│ ├── styles/ # CSS styles
112+
│ └── utils/ # General utilities
113+
└── Various config files # Configuration files
32114
```
33115

34-
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.
35-
36-
Images can be added to `src/assets/` and embedded in Markdown with a relative link.
37-
38-
Static assets, like favicons, can be placed in the `public/` directory.
116+
## Configuration Files
39117

40-
## 🧞 Commands
118+
| File | Purpose |
119+
| ------------------ | -------------------------------- |
120+
| `.env.example` | Example environment variables |
121+
| `astro.config.mjs` | Main configuration |
122+
| `astro.sidebar.ts` | Documentation sidebar structure |
123+
| `package.json` | Project dependencies and scripts |
41124

42-
All commands are run from the root of the project, from a terminal:
125+
## Technologies Used
43126

44-
| Command | Action |
45-
| :------------------------ | :----------------------------------------------- |
46-
| `npm install` | Installs dependencies |
47-
| `npm run dev` | Starts local dev server at `localhost:4321` |
48-
| `npm run build` | Build your production site to `./dist/` |
49-
| `npm run preview` | Preview your build locally, before deploying |
50-
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
51-
| `npm run astro -- --help` | Get help using the Astro CLI |
127+
| Category | Technology | Description |
128+
| ------------------- | --------------------------------------------------- | ------------------------------------------ |
129+
| **Framework** | [Astro](https://astro.build/) | Web framework for content-driven sites |
130+
| **Docs Framework** | [Starlight](https://starlight.astro.build/) | Documentation toolkit for Astro |
131+
| **Styling** | [Tailwind CSS](https://tailwindcss.com/) | Utility-first CSS framework |
132+
| **UI Components** | [React](https://react.dev/) | UI library (via Astro Islands) |
133+
| **Package Manager** | [pnpm](https://pnpm.io/) | Fast, disk space efficient package manager |
134+
| **Search** | [Algolia DocSearch](https://docsearch.algolia.com/) | Documentation search |
135+
| **Authentication** | [Firebase](https://firebase.google.com/) | Auth and backend services |
136+
| **Deployment** | [Vercel](https://vercel.com/) | Hosting platform |
52137

53-
## 👀 Want to learn more?
138+
## Contributing
54139

55-
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).
140+
- Ensure code adheres to ESLint rules (`pnpm lint`)
141+
- Format code using Prettier (`pnpm format`)

‎astro.sidebar.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import type { StarlightUserConfig } from "@astrojs/starlight/types";
22
import { openAPISidebarGroups } from "starlight-openapi";
3-
import { group, type NestedSidebarItem } from "./config/sidebar";
3+
import { group, type NestedSidebarItem } from "./src/config/sidebar";
44
import { ENV } from "./src/lib/env";
55

66
// Define icons for top-level sidebar groups

‎config/sidebar.ts‎ renamed to ‎src/config/sidebar.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import enLabels from "../src/content/nav/en";
1+
import enLabels from "../content/nav/en";
22

33
// Define key types for navigation
44
type NavKey = keyof typeof enLabels;

0 commit comments

Comments
 (0)