kristoferssolo/Theory-of-Algorithms-Cheatsheet
1
0
Fork 0
mirror of https://github.com/kristoferssolo/Theory-of-Algorithms-Cheatsheet.git synced 2025-10-21 20:10:39 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: add readme

Browse Source
This commit is contained in:
Kristofers Solo 2025-06-15 02:39:40 +03:00
parent 16c21da5cd
commit e67ff9fdaf
Signed by: kristoferssolo
GPG Key ID: 8687F2D3EEE6F0ED
1 changed files with 118 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
README.md Normal file
View File

@ -0,0 +1,118 @@
# Typst Project Template with Automated Releases
This repository serves as a template for creating documents with [Typst](https://typst.app/), a modern, markup-based typesetting system. It includes a pre-configured GitHub Actions workflow that automatically compiles your document and creates a GitHub Release whenever you push a new version tag.
## Features
- **Automated PDF Compilation**: Automatically compiles `main.typ` into `main.pdf` on every run.
- **Dependency Caching**: Uses `typst-community/setup-typst` to cache dependencies listed in `requirements.typ`, speeding up subsequent builds.
- **Automatic Releases**: Creates a new GitHub Release with the compiled PDF attached whenever a tag matching the `v*.*.*` pattern is pushed.
- **Manual Workflow Trigger**: Allows for manual builds directly from the GitHub Actions tab, perfect for testing changes without creating a release.
## File Structure
```bash
.
├── .github/
│ └── workflows/
│ └── release.yml # The GitHub Actions workflow definition.
├── main.typ # Your main Typst document entry point.
├── requirements.typ # List your Typst package dependencies here.
├── bibliography.yml # A sample bibliography file (if needed).
└── README.md # This file.
```
- **`main.typ`**: This is the heart of your document. All your content should start here.
- **`requirements.typ`**: If your project uses external Typst packages, you should specify them here. The workflow will automatically fetch and cache them. For example:
```typst
#import "@preview/fletcher:0.5.8"
#import "@preview/physica:0.9.5"
```
- **`.github/workflows/release.yml`**: This file defines the Continuous Integration/Continuous Deployment (CI/CD) pipeline. See the "Workflow Breakdown" section below for a detailed explanation.
## How to Use This Template
There are two primary ways to use the automation provided in this template.
### Method 1: Creating a Release/Tag (Recommended)
This is the standard way to publish a new version of your document. The workflow will automatically create a GitHub Release and attach your compiled PDF.
1. **Commit Your Changes**: Make sure all your latest changes to the `.typ` files are committed to your main branch.
```bash
git add .
git commit -m "Finalize version 1.0.0"
```
2. **Tag the Version**: Create a new Git tag that follows the semantic versioning format (e.g., `v1.0.0`, `v1.2.3`).
```bash
git tag v1.0.0
```
3. **Push the Tag**: Push your commits and the new tag to GitHub.
```bash git push origin main
git push origin v1.0.0
```
Once the tag is pushed, the "Release" workflow will automatically start. It will compile `main.typ` and create a new release on your repository's "Releases" page, named `v1.0.0 — <current_date>`, with `main.pdf` attached as an asset.
### Method 2: Manual Build for Testing
If you want to compile the PDF to see the result without creating a public release, you can trigger the workflow manually.
1. Navigate to the **Actions** tab in your GitHub repository.
2. In the left sidebar, click on the **Release** workflow.
3. You will see a message: "This workflow has a `workflow_dispatch` event trigger." Click the **Run workflow** dropdown button.
4. You will be prompted to enter a `version` string. This is for informational purposes in the run log; you can enter any value (e.g., `test-build`).
5. Click the green **Run workflow** button.
The workflow will run, but the final "Release" step will be skipped. You can download the compiled `main.pdf` from the "Artifacts" section on the summary page for that workflow run.
## Workflow Breakdown (`release.yml`)
The automation is powered by the `.github/workflows/release.yml` file. Here is a step-by-step explanation of what it does.
### Triggers
The workflow is triggered by two events:
1. **`push: tags:`**: Runs automatically when a tag matching the pattern `v[0-9]+.[0-9]+.[0-9]+*` is pushed.
2. **`workflow_dispatch:`**: Allows the manual execution described above.
### Permissions
- `contents: write`: This is essential. It grants the workflow permission to create GitHub Releases and upload files (artifacts) to them.
### Job: `build`
The workflow consists of a single job named `build` that runs on an `ubuntu-latest` virtual machine.
- **`actions/checkout@v4`**: This step checks out your repository's code so the workflow can access your `.typ` files.
- **`typst-community/setup-typst@v4`**: This community action installs the specified version of Typst (`0.13`). The `cache-dependency-path` key is configured to look at `requirements.typ`, enabling caching of Typst packages to make future runs faster.
- **`Compile Typst files`**: A simple shell command that runs the Typst compiler, taking `main.typ` as input and producing `main.pdf`.
```bash
typst compile main.typ main.pdf
```
- **`Upload PDF file`**: This step uses `actions/upload-artifact@v4` to save the generated `main.pdf` as a workflow artifact. This is useful for every run, as it allows you to download the PDF even if a release isn't created.
- **`Get current date`**: Creates a timestamp that is used in the release name for uniqueness.
- **`softprops/action-gh-release@v1`**: This is the final step that creates the release.
- `if: github.ref_type == 'tag'`: This crucial condition ensures this step **only runs if the workflow was triggered by a tag**. It is skipped during manual `workflow_dispatch` runs.
- `name: "${{ github.ref_name }} — ${{ env.DATE }}"`: Sets the release title to the tag name (e.g., `v1.0.0`) plus the date.
- `files: main.pdf`: Attaches the compiled `main.pdf` to the release.
## Customization
- **Typst Version**: To use a different version of Typst, simply change the `typst-version` in the `release.yml` file.
- **Main File**: If your main Typst file is not named `main.typ`, you will need to update the `Compile Typst files` and `Release` steps in `release.yml`.
- **Release Assets**: You can add more files to the release (e.g., a ZIP of the source code) by modifying the `files:` list in the `Release` step.