The world of open-source software offers users an array of options for hosting and managing content, providing the much-needed autonomy over their digital presence. However, it often requires significant investment of time and might not deliver a result at par with ready-to-use commercial platforms. In this post, we will explore a combination of open-source tools that might help overcome this hurdle: Docusaurus, Tina CMS, and GitHub Pages.

Docusaurus is a remarkable solution for static content generation. Originating as a tool primarily for documentation websites, Docusaurus has proven to be a versatile tool for blogging as well. Its large ecosystem supports various plugins, making it an adaptable option for different requirements. The main challenge with Docusaurus lies in its content management workflow. It necessitates adding content as markdown files and committing them to git. While this approach ensures version control, it can be cumbersome when you need to make a quick post.

To tackle this, we bring in our second tool: Tina CMS. Tina is a user-friendly markdown editor that can be integrated with various Content Management Systems (CMS). Its primary function is to streamline the process of editing and updating content by directly committing the changes to git. By eliminating the need to manually update markdown files and commit them to git, Tina CMS enhances the overall user experience and content management workflow.

Lastly, we have GitHub Pages, a simple and effective solution for web hosting directly from a GitHub repository. Its simplicity makes it an ideal choice for those who manage their source code on GitHub. Furthermore, GitHub Pages also supports GitHub Actions, a CI/CD infrastructure that can automate the static generation of the website. This automation significantly reduces manual effort, making it a time-efficient solution.

In combination, Docusaurus, Tina CMS, and GitHub Pages present a strong case for a comprehensive, open-source, blogging solution. Docusaurus offers an efficient platform for static content generation, Tina CMS simplifies content updates, and GitHub Pages provide a hassle-free hosting solution. Each tool addresses different aspects of the blogging process, together offering a workflow that aligns with the benefits of commercial platforms while maintaining the flexibility of open-source software.

For users navigating the open-source landscape, this triad can potentially be the answer to their blogging needs. Exploring and integrating these tools could pave the way to a more streamlined, autonomous, and effective blogging process.

How to set it up

1. Fork the repo from https://github.com/tinacms/tinasaurus to your own github account. This way you can always pull down any improvements that they do to the repo later on.

2. Start the project locally by running yarn tina in a terminal and open http://localhost:3000/admin in a browser.

3. Configure your docusaurus.config.js to deploy to GitHub Pages. Modify the fields url, baseUrl, and organizationName and projectName under presets.docusaurus-plugin-content-docs as per your project.

module.exports = {
  url: 'https://<GITHUB_USERNAME>.github.io',
  baseUrl: '/<REPO_NAME>/',
  projectName: '<REPO_NAME>',
  organizationName: '<GITHUB_USERNAME>',
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          routeBasePath: '/',
          editUrl:
            'https://github.com/<GITHUB_USERNAME>/<REPO_NAME>/edit/main/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
};

4. Setup GitHub Actions. In your project root, create a new directory named .github/workflows and inside this, create a new file deploy.yml. This is the GitHub Actions configuration file.

Put the following content in the deploy.yml file:

name: Deployment

on:
  push:
    branches:
      - main # Set a branch to deploy

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install Dependencies
        run: yarn

      - name: Build
        run: yarn build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

5. Grant Github Action Workflows read and write permissions to your repository. Otherwise it will fail to push the generated files to the gh-pages branch.

5. Commit and Push. Commit all your changes and push to the main branch.

git add.
git commit - m "Setup GitHub Actions for Docusaurus"
git push

6. Activate GitHub Pages. Go to your repository settings on GitHub, scroll down to the GitHub Pages section, select gh-pages branch as your source, and save.

After you have pushed your changes to the repository, GitHub Actions should start a new job to deploy your Docusaurus site to GitHub Pages. You can check the status of the job in the "Actions" tab of your repository. After the deployment, you can access your site at https://\<GITHUB_USERNAME>.github.io/\<REPO_NAME>/.