Kodama Tutorials [index-en-US]
Kodama Tutorials [index-en-US]
You can directly download the binary file from the Github Release page based on the architecture of your target device. For use in Android environments like Termux, choose the When the Github Release page does not have a file suitable for your device, you can start by building from source code yourself, which is also quite easy. The command For example, if the final deployment URL is https://www.example.com/blog, which is not the root directory of the domain, to ensure the correctness of the generated links, the user should specify the Note that this is only necessary if you are deploying to a specific subdirectory.
If you are using it locally, you don’t need to consider this issue. If you want to view the generated pages in the Although the Markdown files processed by Kodama are syntactically compliant with the CommonMark standard, it implements many features beyond CommonMark. To distinguish these additional features syntactically, users must follow the rules below when using these extra functionalities. First and foremost, it is important to emphasize that paths for both embedded files 1 and internal links 2 should be absolute paths relative to the current workspace, starting with The difference between the embed syntax and the standard link syntax The reason for using these special suffixes in this syntax is that many Markdown editors 1 can recognize them correctly, allowing for navigation between files. Most of the time, the Such as Visual Studio Code. Often, for quite simple Typst text, users will want a way to display it inline, corresponding to the inline math context in $\KaTeX$. This is where inline Typst comes in. Inline Typst might be the true strength of Kodama, as the designers have made great efforts to make it behave just like or at least very close to $\KaTeX$ inline formulas, so that the inline formulas written in Typst do not appear inferior when mixed with $\KaTeX$. Inline Typst also uses link-like syntax, but in this case, no file is actually linked. The Values of parameters are separated by The embedded file can be either a standalone Markdown or Typst file. The embedding operation will merge the content of the linked file into the position of the link. For Markdown, it will become a child Internal links are used to link to other Markdown files within the same Kodama project. Compared to external links, internal links use a special style. A reference GitHub Workflow configuration can be found here 1. The only thing to note is the environment variable Provided by Hong Jiarong.Installation [install-en-US]
aarch64-unknown-linux-musl architecture.
Compilation [compile-en-US]
kodama compile or its abbreviation kodama c will build HTML files based on the input Markdown workspace path. By default, these files are placed in the publish folder within the workspace path. Even with the --root parameter, it is still recommended for all users to execute kodama c in the directory where the index.md file is located.shell [compile-help]
$ kodama c --help
Compile current workspace dir to HTMLs
Usage: kodama.exe compile [OPTIONS]
Options:
-b, --base <BASE> Base URL or publish URL (e.g. https://www.example.com/) [default: /]
-o, --output <OUTPUT> Path to output dir [default: ./publish]
-r, --root <ROOT> Configures the project root (for absolute paths) [default: ./]
-d, --disable-pretty-urls Disable pretty urls (`/page` to `/page.html`)
-s, --short-slug Hide parents part in slug (e.g. `tutorials/install` to `install`)
-f, --footer-mode <FOOTER_MODE> Specify the inline mode for the footer sections [default: link] [possible values: link, embed]
-h, --help Print help
--base compilation parameter, like so:kodama c -b=https://www.example.com/blog
Preview [publish-en-US]
publish/ directory locally, you typically need a local HTTP server. You can use any tool you are familiar with to accomplish this. Here, miniserve is recommended. After installing it, you can run the following command in the root path of your Kodama project to serve the pages locally.miniserve ./publish --index index.html --pretty-urls
Link rules [link-rules-en-US]
/.Embed Syntax [embed-syntax-en-US]
[text](url) is that the url in the embed has a special suffix, and it can only be one of the following:
.md#:embed, to embed Markdown..typ#:block, to embed the compiled SVG from Typst and display it as a block-level element centered..typ#:span, to embed the compiled SVG from Typst and display it as an inline element (less commonly used)..typ#:shared, to import the Typst file within the context of the current file, where text is used to provide the scope of the imported definitions, such as all definitions with *. This is used in conjunction with inline Typst syntax.text in the embed syntax is left empty. However, since only Markdown embeds create child sections, the text can be used to set whether the section is expanded by default and its state in the table of contents. These settings are made up of a series of specific characters, and their functions are independent of each other, so the order in which they are written can be arbitrary.
+, indicates that the current section uses a counter.-, collapses the current section by default. Consequently, if this section also has a series of child sections, these child sections will not appear in the table of contents on the current page.., hides this section in the table of contents on the current page.Inline Syntax [inline-syntax-en-US]
url part is used to specify the inline mode and the margin parameter. In most cases, users do not need to manually set the margin parameter to achieve a good presentation. The inline mode is a parameter designed for the convenience of the Markdown editor’s own preview feature. When the user enters math, the content of the text part is automatically enclosed with ${}$ before being compiled by Typst. Here are some examples:
[$x^2$](inline), x^2 is a valid formula for both $\KaTeX$ and Typst. In this case, the Markdown editor’s own preview feature can correctly display it as $x^2$. However, this example is so simple that there is no real reason to use Typst.# is a frequently used character in Typst. If you still write ${}$ manually, it would lead to a poor preview experience in the editor. This is where the inline mode parameter math comes into play. Now you can write the first example as [x^2](inline-math).-. The positions of math and margin are fixed, which means that if both parameters are present, you can only write margin after math. The margin is composed of text in the form of {x}-{y}, where x and y are any valid Typst length values, such as 0pt-2pt. When y is missing, y will adopt the value of x.section.Github CI [github-workflow-en-US]
$PAGE_URL, which is used to specify the URL of the page to be deployed. You can set these in the settings/variables/actions section of your repository.workflow.yml [workflow-yml]
name: Deploy Kodama site to Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
# Default to bash
defaults:
run:
shell: bash
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Install Kodama & Typst
run: |
cargo install --git https://github.com/kokic/kodama.git
sudo snap install typst
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
- name: Setup Pages
id: pages
uses: actions/configure-pages@v5
- name: Build with Kodama
run: |
kodama c -b $PAGE_URL
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./publish
# Deployment job
deploy:
environment:
name: github-pages
url: $PAGE_URL
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4