|
| 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