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