Gatsby Portfolio Site Assistant

Expert guidance for working with Gatsby v3 portfolio websites featuring markdown-based content management, styled-components styling, and GraphQL data layer.

Context

This skill helps you work with personal portfolio websites built using:

Development Workflow

When working with this codebase:

1. **Setup & Installation**

- Run `yarn` to install all dependencies

- Use `npm start` or `gatsby develop` to start the dev server at http://localhost:8000

- Run `gatsby clean` if you encounter build cache issues

2. **Making Changes**

- Use webpack aliases for imports: `@components`, `@config`, `@fonts`, `@hooks`, `@images`, `@pages`, `@styles`, `@utils`

- Format code with `npm run format` (uses Prettier)

- Lint files with `npx eslint <file>` when needed

- Pre-commit hooks automatically format and lint staged files via husky + lint-staged

3. **Content Management**

- Edit markdown files in `/content/` directories:

- `/content/jobs/` - Work experience entries

- `/content/featured/` - Featured projects (homepage highlights)

- `/content/projects/` - Additional project listings

- `/content/posts/` - Blog posts

- Include proper frontmatter (title, date, slug, tags, etc.)

- Images referenced in markdown are optimized via gatsby-remark-images

4. **Component Development**

- Create reusable components in `/src/components/`

- Section components go in `/src/components/sections/`

- Use styled-components for styling

- Reference theme colors from `/src/config.js`

- Homepage sections render in order: Hero → About → Jobs → Featured → Projects → Contact

5. **Page Creation**

- Static pages: Add to `/src/pages/`

- Dynamic pages: Configure in `gatsby-node.js`

- Blog posts auto-generate from `/content/posts/` using `src/templates/post.js`

- Tag pages auto-generate at `/pensieve/tags/{tag}/` using `src/templates/tag.js`

6. **Styling**

- Global styles in `/src/styles/`

- Theme configuration in `/src/config.js` (navy/green color scheme)

- Custom fonts in `/src/fonts/`

- Use styled-components for component-level styles

7. **Data Queries**

- Use GraphQL to query markdown content transformed by gatsby-transformer-remark

- Access frontmatter and markdown body in components

- Test queries at http://localhost:8000/___graphql during development

8. **Configuration**

- Site metadata and plugin config: `gatsby-config.js`

- Build-time logic and webpack config: `gatsby-node.js`

- App-level config (email, social, nav, colors): `/src/config.js`

9. **Build & Deploy**

- Run `npm run build` to create production build in `/public`

- Preview with `npm run serve`

- Includes PWA features (manifest, offline support, sitemap, robots.txt)

Key Technical Considerations

Common Tasks

**Adding a new project:**

1. Create markdown file in `/content/featured/` or `/content/projects/`

2. Include required frontmatter (title, cover, tech, github, external, etc.)

3. Write project description in markdown body

4. Restart dev server if needed

**Adding a blog post:**

1. Create markdown file in `/content/posts/`

2. Include frontmatter (title, date, slug, tags)

3. Page auto-generates at `/pensieve/{slug}/`

**Modifying homepage sections:**

1. Edit components in `/src/components/sections/`

2. Update config in `/src/config.js` if changing links or metadata

3. Changes hot-reload in development

**Debugging build issues:**

1. Run `gatsby clean` to clear cache

2. Check for SSR-incompatible code (window/document references)

3. Verify markdown frontmatter is valid

4. Check GraphQL queries in components

Constraints