polymech/site-template
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme

Browse Source
This commit is contained in:
lovebird 2025-03-10 17:42:44 +01:00
parent d1a576da3c
commit a036fcd76b
1 changed files with 144 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
README.md
View File

@ -1,111 +1,144 @@
# Williamsburg
# Astro Site Documentation
## Template Integrations
- Tailwind CSS v4
- Astro SEO - Powered by [@astrolib/seo](https://github.com/onwidget/astrolib/tree/main/packages/seo)
- Astro Sitemap - https://docs.astro.build/en/guides/integrations-guide/sitemap/
This README provides comprehensive documentation for this Astro-based website project.
## Template Structure
## 🚀 Project Overview
The template follows a typical Astro project structure. You'll find the following key directories and files:
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/
├── public/ # Static assets
├── src/
│ └── pages/
│ └── index.astro
└── package.json
│ ├── 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
```
- `src/pages/`: Contains `.astro` and `.md` files. Each file becomes a route in your project based on its name.
- `src/components/`: Ideal for placing your Astro/React/Vue/Svelte/Preact components.
- `public/`: For static assets such as images that you want to serve directly.
## 📚 Content Collections
## Commands
The site utilizes Astro's content collections to manage structured content. Collections are defined in `src/content.config.ts` and include:
All commands are run from the root of the project, from a terminal:
- **Blog Posts**: Articles with frontmatter for metadata like title, date, author, etc.
- **Authors**: Information about content authors.
| 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 |
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
Learn more - Explore more through Astro's official [documentation](https://docs.astro.build).
## 🧩 Components
------
Updated on 30th December 2024
The site includes reusable UI components located in `src/components/`:
## This update includes:
- Add Tailwind CSS v4 Beta
On this version, Tailwind CSS is now beta version from Tailwind CSS V4, this means that there's no `tailwind.config.mjs` file anymore. From now on, all style will be added on the `css` file. You can find the styles on the `src/styles/global.css` file.
- Astro V5
This update includes Astro V5, which is a major update that includes several new features and improvements.
- **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.
- Astro SEO by @astrolib/seo
This update includes the integration of the Astro SEO package by @astrolib/seo, is an integration that makes managing your SEO easier in Astro projects. It is fully based on the excellent Next SEO library
## 📏 Layouts
## On the next update
Layouts in `src/layouts/` provide consistent page structures:
- Add Image component from Astro
The Astro Image component is coming back to the themes
- **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
- Reusable components
This template now includes reusable components, such as the `Text` component:
Layouts wrap content with consistent HTML structure, styling, and components.
- Text Component
A versatile and reusable component for handling text across your project, ensuring consistency and easy customization.
## 🌐 Internationalization (i18n)
- **HTML Tags:** Easily change the HTML element (like `p`, `h1`, `span`, `a`) using the `tag` prop, with `p` being the default.
- **Variants:** Pick from preset text styles (such as `displayXL` or `textBase`) for a consistent look.
- **Custom Classes:** Add or adjust styles with the `class` prop.
- **Accessibility:** Customize with additional props like `id`, `href`, `title`, and `style`.
- **Content Slot:** Add any content inside the component, including optional left and right icons.
Example usage:
```astro
<Text tag="h1" variant="displayXL" class="text-center">
Welcome to the new version!
</Text>
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
```
- Button Component
A customizable button component with options to fit your design needs:
The build output will be in the `dist/` directory.
- **Variants:** Choose from predefined styles like `primary` (dark background) and `secondary` (lighter background), with support for dark mode.
- **Sizes:** Select `small` or `medium` for different button heights and padding.
- **Gaps:** Control the spacing between content with the `gapSize` prop (either `small` or `medium`).
- **Custom Classes:** Apply additional styles using the `class` prop.
- **Slots:** Include icons or extra content with optional `left-icon` and `right-icon` slots.
Example usage:
```astro
<Button size="small" variant="primary">Primary small</Button>
```
### Additional Commands
- Wrapper Component
A flexible layout component that helps with consistent spacing and alignment.
- **Preview build**: `npm run preview`
- **Check code**: `npm run astro check`
- **Lint code**: `npm run lint` (if configured)
- **Variants:** The default `standard` variant includes responsive widths, centered content, and padding.
- **Custom Classes:** Add or change styles with the `class` prop.
- **Content Slot:** Easily add any child components or content inside.
## 📝 Contributing
```astro
<Wrapper variant="standard">
Your content goes here
</Wrapper>
```
-----
When contributing to this project, please follow these guidelines:
### [Support](https://lexingtonthemes.com/legal/support/)
### [Documentation](https://lexingtonthemes.com/documentation/)
### [Get your bundle](https://lexingtonthemes.com)
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
### References
[Add your license information here]
-[PWA](https://vite-pwa-org.netlify.app/)