Publish your presentation with Codeberg and litedown

This is a small tutorial on how to publish your presentation with litedown thanks to Codeberg Pages.

0. A word of caution, support Codeberg!

First you should read the link above! Since it may not be the case:

Codeberg Pages is currently provided with a best effort approach. To be exact, the software behind this feature is currently in maintenance mode. Please do not rely on it for critical websites, as we can’t guarantee high availability like some other providers do.

If you follow the issue linked you will see that Codeberg is lacking resources to fully maintain it. If you can, keep in mind you can join codeberg or donate.

1. You need a codeberg repository

This one is fairly easy! Just use the Codeberg + sign to create a new repository,

2. You need to have a branch named pages

Depending on how you have setup Git your default branch will be main or master.

On your shell:

git status
1
git switch -c pages 
2
echo "In HTML we trust" > index.html
3
git remote add origin ssh://git@codeberg.org/your_username/your_repo.git
4
git add . 
git commit -m "very deep and insightful commit message" 
git push -u origin pages

1

Check on what branch you are, not that important

2

Switch to a branch named pages (similar to git checkout -b a_branch)

3

Create a very bare bone hmtl file

4

If it was not done before it will add an “origin” repository (the repository your created at Codeberg)

5

After having staged and commited some change you are pushing your local branch pages to the origin (ie on Codeberg)

3. In Html We Trust

A quick check at https://your_username.codeberg.page/your_repo/ should let you see if it worked (Replace your_username and your_repo has needed).

In your Codeberg repository you should also have no something like that:

Now,pages is your default branch.

4. Transform sources to HTML

We recommend a specific workflow but feel free to adjust. Let’s start by stating the end goal: having a index.html file updated and pushed into pages in your codeberg origin repository.

Warning

It needs to be index.html! No fancy name allowed, we will see later how we can improve on that.

Working in your source document

We think it is easier to start a new branch (dev-somethingin your local repository) that will be your feature or development branch. You can work, commit here and if needed push it to Codeberg.

Tip

We are using litedown but R markdown or quarto will produce very similar result.

---
config:
  theme: redux
  layout: dagre
---

flowchart LR
    dev_loc("Local Dev.") --"push upstream"--> dev_origin("Origin Dev.")
    dev_loc --"litedown::fuse()" --> I["index.html"]
    I --"litedown::roam()"--> P["Preview in Browser"]    
    dev_origin -- merge --> pages_loc("Local Pages")

Using litedown to generate index.html

To make a litedown slide presentation you can follow Yihui’s vignette.

In litedown you can generate an html document using the fuse() function:

litedown::fuse('slides.Rmd', 'index.html')
# here the Rmd is named slides and converted to index.html
litedown::roam()
# here this will use your R session 

An other option is to use Python’s webbrowser module after “fusing” your .Rmd file.

python -m webbrowser index.html

Those are represented at the bottom part of the workflow.

Pushing your index.html to Codeberg pages

Finally, when you think you are ready you can merge your dev- branch into the pages. You can either decide to merge your dev- to pages on your local repository and push to Codeberg. This is an option here if you are working alone.
Or you can also push your dev- branch in Codeberg and then do a pull request (git push --set-upstream origin dev). This will look like this:

Then you can write your merge commit:

This is it! Overall Codeberg is very close to Git!