Skip to content

Commit c1b6c27

Browse files
authored
Add claude.md with info on the repo structure, to help Claude know where things are (#840)
* Add `claude.md` with info on the repo structure, to help Claude know where things are * Feedback from @cscheid * One more note about `writer` * Add sections on development workflow and testing
1 parent 4a2e154 commit c1b6c27

File tree

1 file changed

+64
-0
lines changed

1 file changed

+64
-0
lines changed

claude.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Quarto Development Guide
2+
3+
## Project Overview
4+
5+
Quarto is an open-source scientific and technical publishing system built on [Pandoc](https://pandoc.org). This repository contains the source code for various parts of the Quarto ecosystem, with the main CLI implementation housed in a separate repository ([quarto-cli](https://github.com/quarto-dev/quarto-cli)).
6+
7+
### Main Components
8+
9+
- **VS Code Extension**: The primary VS Code extension for working with Quarto documents
10+
- **Writer**: An experimental web-based editor for Quarto documents (not used in production yet)
11+
- **LSP**: Language server for Quarto documents
12+
- **Core Packages**: Shared libraries used across multiple components
13+
14+
## Development Workflow
15+
16+
Each component has specific development guidelines. Refer to the corresponding CONTRIBUTING.md files:
17+
18+
- VS Code extension: [apps/vscode/CONTRIBUTING.md](apps/vscode/CONTRIBUTING.md) - Contains detailed instructions for building, debugging, and releasing the extension
19+
20+
## Repository Structure
21+
22+
The repository is organized as a monorepo using Yarn workspaces and Turborepo for build orchestration:
23+
24+
- `apps/`: Contains standalone applications
25+
- `vscode/`: VS Code extension for Quarto
26+
- `writer/`: Experimental web-based Quarto editor (not in production, ignore this for now)
27+
- `lsp/`: Language Server Protocol implementation
28+
- `panmirror/`: WYSIWYG editor component
29+
- `packages/`: Contains shared libraries
30+
- `core/`: Core functionality shared across packages
31+
- `editor-*/`: Editor-related packages
32+
- `quarto-core/`: Quarto-specific core functionality
33+
- Other utility packages
34+
35+
## Build System
36+
37+
Quarto uses [turborepo](https://turbo.build/) to manage the monorepo build process:
38+
39+
- `turbo.json`: Defines the pipeline configuration for common tasks
40+
- Common commands:
41+
- `yarn build`: Builds all packages and applications
42+
- `yarn dev-writer`: Runs the writer app in development mode
43+
- `yarn dev-vscode`: Runs the VS Code extension in development mode
44+
- `yarn lint`: Runs linters across all workspaces
45+
- `yarn build-vscode`: Builds only the VS Code extension and its dependencies
46+
47+
The turborepo pipeline helps optimize build times by caching build artifacts and respecting the dependency graph between packages.
48+
49+
## Testing
50+
51+
Testing procedures vary by component:
52+
53+
- VS Code extension: Run `yarn test-vscode` to compile test files and run them with the vscode-test CLI
54+
- Other components have specific test commands defined in their respective package.json files
55+
56+
57+
## Additional Resources
58+
59+
- [Quarto Website](https://quarto.org)
60+
- [Extension on Microsoft marketplace](https://marketplace.visualstudio.com/items?itemName=quarto.quarto)
61+
- [Extension on Open VSX Registry](https://open-vsx.org/extension/quarto/quarto)
62+
- [Quarto GitHub Organization](https://github.com/quarto-dev)
63+
64+
# Instructions

0 commit comments

Comments
 (0)