Watch the video on YouTube!
Once you start generating a static website using Org Mode's publishing system, the next thing you'll probably want to know is how to publish the site so that other people can check it out.
In this video, you'll learn how to set up automatic publishing of your Org Mode website every time you push a commit to your Git repository.
To get started, make sure you have an account on one of the websites we'll talk about today: GitHub or SourceHut.
On GitHub, it's free to create an account and do everything that we'll talk about in this video. You can create an account here:
It's also free to create an account on SourceHut but they've recently had to require payment to use their build service because crypto miners ruined the party for everyone. Fortunately you can sign up with a "maintainer" account for as little as $2 per month:
There are other ways you can get free service on SourceHut, check out this entry in the Billing FAQ.
Both are great options and it will be similarly easy to publish sites on each.
GitHub is the well-known mainstream option, doesn't hurt to have an account there.
SourceHut is a more hacker-focused site with a totally different philosophy that you might appreciate. You can learn more about it by checking out their website at sourcehut.org. Be aware, there are some restrictions about what kind of content you can publish on SourceHut pages!
On either hosting site, you'll need a repository where you store your Org Mode website's content files and the build script that we created in the previous video of this series. If you haven't seen that yet, check it out here:
We'll be starting from the code in the org-website-example repository from that video, so you might want to clone that repo, create a new folder on your filesystem, and copy those site files into it as a starting point.
I won't be going into depth about how to use Git in this episode, but I'll give a brief rundown of the commands you need to know to turn your site files into a Git repository and "commit" the changes:
# Copy the starting point files git clone https://github.com/SystemCrafters/org-website-example # Create the folder for the local repo mkdir my-org-site cd my-org-site cp -R ../org-website-example/* . # Initialize the Git repository and make your first commit git init git add -A git commit -m "My first commit!"
Now every time you make changes to your site, you can go to your my-org-site folder and run the following commands:
git add -A git commit -m "Updating website files" # We will talk about this step in a bit # git push origin master
I recommend reading the Git Book if you're a beginner to Git and want to learn more about how to use it.
To publish a website with GitHub Pages, you'll need to create a repository with a specific name:
You can go to https://github.com/new and create a public repository with this name, making sure to use your actual GitHub username! Don't select any of the checkboxes, we will push our own repository once the GitHub repo is created.
Now that the repo is created, you can copy the link that they give you so that you can configure your local repository to push there:
# To use HTTPS git remote add origin https://github.com/yourusername/yourusername.github.io.git # To use SSH if you've set up a public key git remote add origin email@example.com:yourusername/yourusername.github.io.git
Authenticating to GitHub can be a little tricky if you've never done it before, consult this documentation page for more details!
Once you've created the repository, you can push your local repository there using git push:
git push origin master
You'll need to run this after every commit you make so that the changes go to the hosted repository!
On SourceHut, you can create a new repository by heading to the following link. It does not require a specific name!
Just make sure you set up your SSH key first since this is the only way to authenticate to git.sr.ht.
Once the repository is created, you can configure it as a remote for your local repository:
git remote add origin firstname.lastname@example.org:~yourusername/my-org-site git push origin master
SourceHut allows you to publish pages for a personal site (yourusername.srht.site) or any custom domain you choose using a simple HTTP-based API.
Now we can set up a build configuration that will automatically publish your website every time you push a commit to its repository!
This is possible by using a "continuous integration" service like GitHub Actions or SourceHut Builds. This type of service enables you to run a build script for your repository on a machine in the cloud so that you can do things like run tests on code or publish a website.
I'll show you example build configurations for both GitHub and SourceHut that you can copy and paste to get started, only with a couple of small tweaks if you decide to use SourceHut.
This file should be placed in your repository at .github/workflows/publish.yml. Here's what it does:
name: Publish to GitHub Pages on: push: branches: - master jobs: publish: runs-on: ubuntu-latest steps: - name: Check out uses: actions/checkout@v1 - name: Install Emacs run: sudo apt install emacs-nox --yes - name: Build the site run: ./build.sh - name: Publish generated content to GitHub Pages uses: JamesIvesemail@example.com with: branch: gh-pages folder: public
Add this file to your repository folder, commit it, and push it to your GitHub repository using the commands I showed you before.
You can watch the progress of the "Publish to GitHub Pages" action from the Actions tab on your repository.
After it completes, the site still won't be published because we need to take one final step to configure your site! Click the Settings tab on your repo, click the Pages tab on the left side of the Settings page, then change the Source Branch to gh-pages and click Save.
After a minute or two your site will now be live!
This file should be placed in your repository at .build.yml. Here's what it does:
YOU MUST CHANGE THESE THINGS:
image: archlinux packages: - emacs-nox oauth: pages.sr.ht/PAGES:RW sources: - https://git.sr.ht/~username/my-org-site environment: site: username.srht.site tasks: - build: | # Generate site files (make sure to update folder name!) cd my-org-site ./build.sh # Bundle the site cd public tar -czf /home/build/html.tar.gz . - upload: | tar -ztvf html.tar.gz acurl --fail-with-body https://pages.sr.ht/publish/$site -Fcontentfirstname.lastname@example.org
After committing and pushing this file to your SourceHut repository, you can monitor the build by going to the builds page for your account:
Once the build has completed you can visit your site at https://yourusername.srht.site! It may take a minute or so before it shows up.
If the build fails, double-check all of the information in your .build.yml file to ensure that you didn't miss anything!
I won't go into too many details here because the documentation pages for both GitHub and SourceHut cover this pretty well.
It is possible to set up a custom domain to point to your website on either of these platforms!
If you don't have a domain for your website yet, you can get one and support the channel at the same time by using my Namecheap affiliate link!
Hopefully these instructions helped you get a new site running using Emacs, Org Mode, and Git.
In future videos of this series, we'll learn how to customize the style of Org Mode sites and also add useful features like RSS feeds and site maps!