Kolibry

Static Hosting

Build Single Page Applications (SPA)

You can also build the slides into a self-hostable SPA:

$ kolibry build

The generated application will be available under dist/.

You can test the generated build using a web server (Apache, NGINX, Caddy...etc.) or in the project you can directly run: npx vite preview.

Then you can host it on GitHub Pages, Netlify, Vercel, or whatever you want. Now you can share your slides with the rest of the world with a single link.

Base Path

To deploy your slides under sub-routes, you will need to pass the --base option. The --base path must begin and end with a slash /; for example:

$ kolibry build --base /talks/my-cool-talk/

Refer to Vite's documentation for more details.

Provide Downloadable PDF

You can provide a downloadable PDF to the viewers of your SPA with the following config:

---
download: true
---

Kolibry will generate a PDF file along with the build, and a download button will be displayed in the SPA.

You can also provide a custom URL for the PDF. In that case, the rendering process will be skipped.

---
download: 'https://myside.com/my-talk.pdf'
---

This can also be done with the CLI option --download (boolean only).

$ kolibry build --download

When using the download option, you can also provide the export options:

Output directory

You can change the output directory using --out.

$ kolibry build --out my-build-folder

Watch mode

By passing the --watch option the build will run in watch mode and will rebuild anytime the source changes.

$ kolibry build --watch

Multiple entries

You can also build multiple slides at once.

$ kolibry build slides1.md slides1.md

Or

$ kolibry build *.md

In this case, each input file will generate a folder containing the build in the output directory.

Examples

Here are a few examples of the exported SPA:

For more, check out Showcases.

Hosting

We recommend to use npm init kolibry@latest to scaffold your project, which contains the necessary configuration files for hosting services out-of-the-box.

Netlify

Create netlify.toml in your project root with the following content.

[build.environment]
  NODE_VERSION = "14"

[build]
  publish = "dist"
  command = "npm run build"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Then go to your Netlify dashboard and create a new site with the repository.

Vercel

Create vercel.json in your project root with the following content.

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Then go to your Vercel dashboard and create a new site with the repository.

GitHub Pages

To deploy your slides on GitHub Pages:

  • upload all the files of the project in your repo (i.e. named name_of_repo)
  • create .github/workflows/deploy.yml with following content to deploy your slides to GitHub Pages via GitHub Actions. In this file, replace <name_of_repo> with name_of_repo. Make sure to leave the leading and trailing slashes in place.
name: Deploy pages

on:
  workflow_dispatch: {}
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: 'lts/*'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build -- --base /<name_of_repo>/

      - uses: actions/configure-pages@v3

      - uses: actions/upload-pages-artifact@v1
        with:
          path: dist

      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v2
  • In your repository, go to Settings>Pages. Under "Build and deployment", select "Github Actions".
  • Finally, after all workflows are executed, a link to the slides should appear under Settings>Pages.