generated from polymech/site-template
145 lines
4.5 KiB
Markdown
145 lines
4.5 KiB
Markdown
# Astro Site Documentation
|
|
|
|
This README provides comprehensive documentation for this Astro-based website project.
|
|
|
|
## 🚀 Project Overview
|
|
|
|
This is a multilingual website built with [Astro](https://astro.build), a modern static site generator. The site features a blog, content collections, and internationalization support. It uses Tailwind CSS for styling and includes various components and layouts for consistent design.
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
/
|
|
├── public/ # Static assets
|
|
├── src/
|
|
│ ├── components/ # UI components
|
|
│ ├── content/ # Content collections
|
|
│ ├── layouts/ # Page layouts
|
|
│ ├── pages/ # Page routes
|
|
│ │ ├── en/ # English pages
|
|
│ │ └── [lang]/ # Other language pages
|
|
│ ├── i18n/ # Internationalization files
|
|
│ └── content.config.ts # Content collection configuration
|
|
├── astro.config.mjs # Astro configuration
|
|
├── tailwind.config.cjs # Tailwind CSS configuration
|
|
└── package.json # Project dependencies
|
|
```
|
|
|
|
## 📚 Content Collections
|
|
|
|
The site utilizes Astro's content collections to manage structured content. Collections are defined in `src/content.config.ts` and include:
|
|
|
|
- **Blog Posts**: Articles with frontmatter for metadata like title, date, author, etc.
|
|
- **Authors**: Information about content authors.
|
|
|
|
Collections are stored in the `src/content/` directory, organized by language:
|
|
- `src/content/blog/en/` - English blog posts
|
|
- `src/content/blog/[lang]/` - Blog posts in other languages
|
|
|
|
## 🧩 Components
|
|
|
|
The site includes reusable UI components located in `src/components/`:
|
|
|
|
- **Core Components**: Basic UI elements like buttons, cards, and navigation
|
|
- **Blog Components**: Specialized components for the blog section
|
|
- **SEO Components**: Components for SEO optimization
|
|
- **UI Components**: Interface elements like headers, footers, and menus
|
|
|
|
These components help maintain consistent design across the site while making development more efficient.
|
|
|
|
## 📏 Layouts
|
|
|
|
Layouts in `src/layouts/` provide consistent page structures:
|
|
|
|
- **BaseLayout.astro**: The main layout with common elements (header, footer)
|
|
- **BlogLayout.astro**: Specialized layout for blog posts
|
|
- **PostLayout.astro**: Layout for individual blog posts
|
|
- **AboutLayout.astro**: Layout for about pages
|
|
|
|
Layouts wrap content with consistent HTML structure, styling, and components.
|
|
|
|
## 🌐 Internationalization (i18n)
|
|
|
|
The site supports multiple languages through a built-in internationalization system:
|
|
|
|
- Default language is English (`en`)
|
|
- Content is organized by language in directory structures
|
|
- URL format follows `/[lang]/[route]` pattern
|
|
- Translation files are stored in the `src/i18n/` directory
|
|
|
|
Language switching is available to visitors, with localized content and UI elements.
|
|
|
|
## 📦 Dependencies
|
|
|
|
The project relies on the following main dependencies:
|
|
|
|
- **Astro**: Core framework for building the site
|
|
- **Tailwind CSS**: Utility-first CSS framework for styling
|
|
- **@astrojs/tailwind**: Tailwind CSS integration for Astro
|
|
- **@astrojs/mdx**: MDX integration for enhanced markdown
|
|
- **@astrojs/sitemap**: Automatic sitemap generation
|
|
- **@astrojs/image**: Image optimization tools
|
|
|
|
Additional dependencies may include utility libraries and development tools.
|
|
|
|
## 🛠️ Development Instructions
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js (v16 or later)
|
|
- npm or yarn
|
|
|
|
### Getting Started
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd <project-directory>
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
# or
|
|
yarn install
|
|
```
|
|
|
|
3. Start the development server:
|
|
```bash
|
|
npm run dev
|
|
# or
|
|
yarn dev
|
|
```
|
|
|
|
4. Open your browser and visit `http://localhost:3000`
|
|
|
|
### Building for Production
|
|
|
|
```bash
|
|
npm run build
|
|
# or
|
|
yarn build
|
|
```
|
|
|
|
The build output will be in the `dist/` directory.
|
|
|
|
### Additional Commands
|
|
|
|
- **Preview build**: `npm run preview`
|
|
- **Check code**: `npm run astro check`
|
|
- **Lint code**: `npm run lint` (if configured)
|
|
|
|
## 📝 Contributing
|
|
|
|
When contributing to this project, please follow these guidelines:
|
|
|
|
1. Create components in the appropriate directories
|
|
2. Follow the existing code style and naming conventions
|
|
3. Add proper documentation for new features
|
|
4. Test your changes before submitting
|
|
|
|
## 📄 License
|
|
|
|
[Add your license information here]
|
|
|