1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
[[!meta title="Hosting with Codeberg Pages"]]
[[!meta date="2022-07-29"]]
I recently switched the [pblog](https://pblog.bt.ht) project repo over from Sourcehut to Codeberg (mostly for UX reasons) and it got me looking into [Codeberg Pages](https://codeberg.page). It seemed like a cleaner approach to host my personal blog on the same platform I planned to also share the source code.
I decided to share the setup process here since I couldn't find a straightforward guide explaining everything required to get going. So, let's dig in.
## Create the Repos
**Disclaimer**: My personal blog uses [pblog](https://pblog.bt.ht), so although these instructions will be catered towards that SSG the same concept *should* apply for any other generator (Jekyll, Hugo, Next, etc.).
The first step is to create the main repo that would house the core files of `pblog`. Then we need to make a separate repo simply called `pages`. This second project is where all the generated "static" files get rendered.
*Side note*: Be sure to at least include a `README` file in that `pages` repo. This will avoid any errors or warnings when setting up our submodules in the next steps.
## Configuration Edits
Once your two repos are created, you will need to make some minor edits to the `_config.sh` in the core `pblog` project to tell the build script where the generated files should go (in this case the `pages` repo):
OUTPUT="_output/pages/"
## The Submodule
Using terminal, navigate to the `_output/` directory in your core `pblog` project. Run the following, remembering to replace the USERNAME parameter with your own:
git submodule add git@codeberg.org:USERNAME/pages.git
If everything worked correctly you should now have a `.gitmodules` file in your main `pblog` project. If you get any errors, you might need to include the name of the directory at the end of the command:
git submodule add git@codeberg.org:USERNAME/pages.git pages
## The Workflow
Now you can make changes, add new posts and pages in the main `pblog` project and have those generated files render into your other `pages` repo. For this workflow, I simply push commits to both projects when I am happy with my changes but I'm sure you could look into automating this process (ie. a single push from the `pblog` repo forces a the `pages` repo to also update).
Now you can navigate to the standard Codeberg Pages URL to see it in action:
USERNAME.codeberg.page
If you want to use your own custom domain (who doesn't?) then continue reading.
## Custom Domains (Optional)
The first thing you will need to do is add a `.domains` file to your `pages` root directory. In this file you will want to list your custom domain on the first line, followed by the standard Codeberg pages URL below it. Like so:
yourcustomdomain.com
USERNAME.codeberg.page
I'm keeping this very basic, but I suggest you look further into the [official documentation](https://docs.codeberg.org/codeberg-pages/#custom-domains) if there are any extra settings you'd like to tinker with.
The final step is configuring a `CNAME` DNS setting through your registrar:
@ -> USERNAME.codeberg.page
Give the DNS settings a bit of time to take (24-48 hours) and you'll have your custom domain working just fine.
Happy hosting!
|
