Skip to content

Commit ba6da9c

Browse files
conradolandiaconradolandia
committed
Improve README.md and CONTRIBUTING.md with more comprehensive documentation
1 parent 436d97d commit ba6da9c

File tree

2 files changed

+353
-75
lines changed

2 files changed

+353
-75
lines changed

‎CONTRIBUTING.md‎

Lines changed: 200 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,202 @@
11
# Contributing to the Spyder Website
22

3-
1. Create a fork of the repository
4-
2. Clone it and create a new branch for your changes
5-
3. Install dependencies with `npm install`
6-
7-
## Creating a Blog Post
8-
9-
1. If the blog post author(s) haven't been added yet:
10-
1. Create a new folder in `static/assets/authors` using a simple identifier (no spaces/special characters)
11-
2. Inside this folder:
12-
- Add a square avatar image (recommended: 512×512px WEBP)
13-
- Create `metadata.json` with:
14-
```json
15-
{
16-
"name": "Author's Display Name",
17-
"image": "filename.webp"
18-
}
19-
```
20-
21-
2. Create a blog post folder in `src/routes/blog` (name becomes URL slug - lowercase, no spaces)
22-
23-
3. Add a `+page.md` file with this frontmatter:
24-
```yaml
25-
---
26-
title: Blog Post Title # Required
27-
author: author-id # Required. For multiple authors, use an array of identifiers
28-
pub_date: YYYY-MM-DD # Required
29-
category: Category Name # Optional
30-
tags: Tag1, Tag2 # Optional
31-
summary: Concise overview of content # Required
32-
---
33-
```
34-
35-
5. Write content using mdsvex Markdown:
36-
- [Never indent code blocks](https://mdsvex.pngwn.io/docs#limitations)
37-
- Use standard Markdown syntax for formatting
38-
39-
6. For images:
40-
```markdown
41-
![Meaningful description](image.webp "Optional caption")
42-
```
43-
- Store images in the post's folder
44-
- All images require *descriptive* alt text (avoid "image of...", "picture of...", "photo of...", etc.)
45-
46-
7. Preview locally with:
47-
```bash
48-
npm run dev
49-
```
50-
- Verify post appears at `/blog/`
51-
- Check author metadata and image display
52-
53-
8. There is no need to build for production, the workflow will run the build on GitHub Actions.
54-
55-
9. Create PR against upstream `main` branch.
3+
Thank you for your interest in contributing to the Spyder website! This guide will help you get started with different types of contributions.
4+
5+
## Table of Contents
6+
7+
- [Contributing to the Spyder Website](#contributing-to-the-spyder-website)
8+
- [Table of Contents](#table-of-contents)
9+
- [Getting Started](#getting-started)
10+
- [Development Setup](#development-setup)
11+
- [Types of Contributions](#types-of-contributions)
12+
- [Creating Blog Posts](#creating-blog-posts)
13+
- [Adding New Authors](#adding-new-authors)
14+
- [Creating the Blog Post](#creating-the-blog-post)
15+
- [Code Contributions](#code-contributions)
16+
- [Guidelines](#guidelines)
17+
- [File Structure](#file-structure)
18+
- [Reporting Issues](#reporting-issues)
19+
- [Pull Request Process](#pull-request-process)
20+
- [Review Process](#review-process)
21+
- [Style Guidelines](#style-guidelines)
22+
- [Questions?](#questions)
23+
24+
## Getting Started
25+
26+
1. **Fork the repository** from [spyder-website](https://github.com/spyder-ide/spyder-website)
27+
2. **Clone your fork** locally:
28+
```bash
29+
git clone https://github.com/YOUR-USERNAME/spyder-website.git
30+
cd spyder-website
31+
```
32+
3. **Create a new branch** for your changes:
33+
```bash
34+
git checkout -b your-feature-branch
35+
```
36+
37+
## Development Setup
38+
39+
1. **Install dependencies**:
40+
```bash
41+
npm install
42+
```
43+
44+
2. **Start the development server**:
45+
```bash
46+
npm run dev
47+
```
48+
The site will be available at `http://localhost:5173`
49+
50+
3. **Available scripts**:
51+
- `npm run dev` - Start development server
52+
- `npm run build` - Build for production
53+
- `npm run preview` - Preview production build
54+
55+
## Types of Contributions
56+
57+
We welcome various types of contributions:
58+
59+
- **Blog posts** - Share news, tutorials, or insights about Spyder
60+
- **Bug fixes** - Fix issues in the website functionality
61+
- **Feature enhancements** - Improve existing features or add new ones
62+
- **Documentation** - Improve clarity and completeness of documentation
63+
- **Design improvements** - Enhance UI/UX elements
64+
- **Performance optimizations** - Make the site faster and more efficient
65+
66+
## Creating Blog Posts
67+
68+
### Adding New Authors
69+
70+
If the blog post author(s) haven't been added yet:
71+
72+
1. **Create author folder** in `static/assets/authors/` using a simple identifier (no spaces/special characters)
73+
2. **Add author files**:
74+
- Square avatar image (recommended: 512×512px WEBP format)
75+
- `metadata.json` file:
76+
```json
77+
{
78+
"name": "Author's Display Name",
79+
"image": "filename.webp"
80+
}
81+
```
82+
83+
### Creating the Blog Post
84+
85+
1. **Create post folder** in `src/routes/blog/` (folder name becomes URL slug - use lowercase, no spaces)
86+
87+
2. **Add main content file** `+page.md` with proper frontmatter:
88+
```yaml
89+
---
90+
title: Blog Post Title # Required
91+
author: author-id # Required. For multiple authors, use array: [author1, author2]
92+
pub_date: YYYY-MM-DD # Required (ISO format)
93+
category: Category Name # Optional
94+
tags: Tag1, Tag2 # Optional (comma-separated)
95+
summary: Concise overview of content # Required
96+
---
97+
```
98+
99+
3. **Write content** using mdsvex Markdown:
100+
- [Never indent code blocks](https://mdsvex.pngwn.io/docs#limitations)
101+
- Use standard Markdown syntax for formatting
102+
- Follow our [style guide](#style-guidelines) for consistency
103+
104+
4. **Add images** (if needed):
105+
```markdown
106+
![Meaningful description](image.webp "Optional caption")
107+
```
108+
- Store images in the post's folder
109+
- Use descriptive alt text (avoid "image of...", "picture of...", etc.)
110+
- Prefer WEBP format for better performance
111+
112+
5. **Preview your post**:
113+
```bash
114+
npm run dev
115+
```
116+
- Verify post appears at `/blog/your-post-name`
117+
- Check author metadata and image display
118+
- Test on different screen sizes
119+
120+
## Code Contributions
121+
122+
### Guidelines
123+
124+
- Follow the existing code style and conventions
125+
- Write clear, descriptive commit messages
126+
- Test your changes thoroughly
127+
- Update documentation if needed
128+
129+
### File Structure
130+
131+
- `src/routes/` - Page routes and content
132+
- `src/lib/` - Reusable components and utilities
133+
- `static/assets/` - Static assets (images, fonts, etc.)
134+
- `src/app.css` - Global styles
135+
136+
## Reporting Issues
137+
138+
Before creating an issue:
139+
140+
1. **Search existing issues** to avoid duplicates
141+
2. **Use the issue template** (if available)
142+
3. **Include relevant details**:
143+
- Clear description of the problem
144+
- Steps to reproduce
145+
- Expected vs. actual behavior
146+
- Browser/OS information (if relevant)
147+
- Screenshots (if applicable)
148+
149+
## Pull Request Process
150+
151+
1. **Ensure your changes work locally**:
152+
```bash
153+
npm run dev
154+
# Test your changes thoroughly
155+
```
156+
157+
2. **Keep commits clean and descriptive**:
158+
```bash
159+
git add .
160+
git commit -m "Add: New blog post about feature X"
161+
```
162+
163+
3. **Push to your fork**:
164+
```bash
165+
git push origin your-feature-branch
166+
```
167+
168+
4. **Create Pull Request**:
169+
- Target the `main` branch
170+
- Use a clear, descriptive title
171+
- Fill out the PR template (if available)
172+
- Link any related issues
173+
174+
5. **After submission**:
175+
- Be responsive to feedback
176+
- Make requested changes promptly
177+
- Keep your branch updated with main if needed
178+
179+
### Review Process
180+
181+
- All PRs require review before merging
182+
- CI/CD will automatically build and test your changes
183+
- Reviewers may request changes or ask questions
184+
- Once approved, maintainers will merge your PR
185+
186+
## Style Guidelines
187+
188+
- Use clear, concise language
189+
- Follow existing naming conventions
190+
- Maintain consistent formatting
191+
- Optimize images for web (prefer WEBP format)
192+
- Ensure accessibility best practices
193+
194+
## Questions?
195+
196+
If you have questions or need help:
197+
198+
- Check existing [documentation](README.md)
199+
- Search [existing issues](https://github.com/spyder-ide/spyder-website/issues)
200+
- Create a new issue with the "question" label
201+
202+
Thank you for contributing to the Spyder website! 🎉

0 commit comments

Comments
 (0)