CodeFlare · Project documentation

CodeFlare is a competitive programming archive of C++ solutions, templates, and practice, organized by online judge and contest. This branch, docs/project-guide, maintains project guides, the static problem browser's API contracts, and the VitePress documentation site.

Website · Online documentation · Source repository · Source catalog · Contributing

Documentation

Goal	Guide
Integrate problem data and look up fields or error conventions	API reference
Find platforms, templates, and tools	Project structure, generated source catalog
Compile a problem locally	Quick start
Add a solution and record validation	Code and archive conventions, Contributing
Configure an editor and problem imports	Development tools
Update documentation or maintain the website	Maintenance, GitHub Pages maintenance
Browse all documentation topics	Documentation index

The API documentation describes static JSON snapshots and external interfaces used by the website, not an online judging service. Download OpenAPI and JSON Schema contracts from the API reference.

Branch responsibilities

Branch	Contents
main	Algorithm source code, templates, and existing development tools
docs/project-guide	This branch: documentation source, API contracts, project conventions, and build checks
gh-pages	Problem browser, data snapshots, and generated documentation in docs/

Documentation does not need to be merged into main. After a documentation PR merges into this branch, the workflow builds the site and updates only gh-pages/docs/. The source catalog records the default-branch commit it describes; see Maintenance for refresh instructions.

Quick start

Read and check Markdown

Read the documentation directly on GitHub or in a Markdown reader. The checker requires Git and Python 3.10+, with no third-party Python packages.

git clone --branch docs/project-guide https://github.com/xw7qwq/codeflare.git codeflare-docs
cd codeflare-docs
python3 scripts/docs.py check

Keep complete Git history and remote branch references. Catalog and API checks read a recorded commit and origin/gh-pages. Compiling an individual solution requires its language toolchain; see Quick start.

Preview the documentation site

Run from the repository root with Node.js 22+ and npm:

npm --prefix site ci
npm --prefix site run dev

Open http://127.0.0.1:4174/docs/. Stop the server with Ctrl+C.

The development server converts Markdown into site/.content/ at startup. After editing source documents, run npm --prefix site run prepare:docs in another terminal to regenerate page content.

Repository layout

Path	Purpose
README.md, CONTRIBUTING.md	Project entry point and contribution guidelines
docs/	Guides, API documentation, and source catalog
scripts/docs.py	Markdown, relative link, heading anchor, and source catalog checks
scripts/README.md, archive/submissions.json	Archive tools, offline tests, and verified submission receipts
site/package.json	Site dependencies and development and build commands
site/.vitepress/	Site configuration and theme
site/public/api/	OpenAPI and JSON Schema contracts
site/prepare.mjs, site/check-build.mjs	Content conversion and build output checks
site/publish.mjs	Documentation publishing and live verification
.github/workflows/docs.yml	Documentation validation, build, and publishing workflow
.github/workflows/archive.yml	Offline archive tests and source integrity audit

site/.content/, site/.vitepress/dist/, and site/node_modules/ are generated directories. Edit Markdown sources and configuration, and keep generated directories out of commits. Project structure and the source catalog define source categories and counts.

Validation and contributions

After installing site dependencies, run from the repository root:

python3 scripts/docs.py check
npm --prefix site run check:api
npm --prefix site run build
git diff --check

These commands validate documentation and the catalog, API contracts and snapshots, the static site build, and whitespace. By default, API checks read two snapshots from local origin/gh-pages. They do not judge algorithms or establish that the remote site was deployed successfully.

Create a working branch from docs/project-guide, stage changes by path, and describe the reason, changes, and validation in a pull request. Track new Markdown files and local link targets in Git first. See Contributing for the full process.

Domain and deployment

CodeFlare uses codeflare.lucius7.dev. Documentation is published under /docs/, and the static API lives under /data/.

GitHub Pages should publish from the root of gh-pages, with codeflare.lucius7.dev as its custom domain. The publishing script validates the repository, source branch, and domain, then updates only the managed docs/ directory, preserving the problem browser and domain configuration.

API collection 2.0.0 uses the new domain and the xw7qwq/codeflare repository identity while retaining response field structures. See Errors and compatibility for migration details. The source catalog retains its original commit SHA, timestamp, and counting rules.

The workflow checks every PR targeting docs/project-guide and every push to that branch. Only pushes publish. Verify releases through Actions, public pages, and docs/build-info.json; see Maintenance for details.

Content and licensing

Each algorithm source file is used independently; there is no single executable for the entire repository. The archive includes unfinished drafts and template fragments without main. A file's presence in Git or on a website does not mean it passed an online judge. Consult the original judge for the problem statement.

The repository has no single declared open-source license. Retain attribution and follow the applicable licenses when using problem statements, third-party code, or dependencies. This documentation grants no additional permissions.

Related projects

OJFlare uses ojflare.lucius7.dev and is maintained and deployed separately.