Sudden Death Rune Archive Icon Tags Icon Events Icon

PageFind with Jekyll

15 Aug 2024 ↣ 23 Aug 2024
Edit: aberto.
Tags: github>jekyll
Improve this page ⇔ View revision history
  • Understanding the Components
  • Step-by-Step Implementation
  • Explanation and Key Considerations

#Understanding the Components

  • PageFind: A powerful search library designed for static websites, offering a fast and efficient search experience without server-side components.
  • Jekyll Plugin: A custom Ruby plugin (_plugins/pagefind.rb) that automatically triggers PageFind indexing after your Jekyll site is built.
  • GitHub Actions: A CI/CD platform that automates the build and deployment process, ensuring your site is updated whenever changes are pushed to your repository.

#Step-by-Step Implementation

  1. Create the Search Page:
    Add a new Markdown file named search.md to your Jekyll site’s pages directory. This file will contain the search interface:

    --- layout: default title: Site Search permalink: /search/ --- <link href="/pagefind/pagefind-ui.css" rel="stylesheet"> <script src="/pagefind/pagefind-ui.js"></script> <h1 style="text-align: center">Site Search</h1> <div id="search"></div> <p style="text-align: center; font-size: 0.7em">Powered by <a target="_blank" href="https://pagefind.app/">PageFind</a></p> <script> window.addEventListener('DOMContentLoaded', (event) => { new PagefindUI({ element: "#search", showSubResults: true }); }); </script>

  2. Configure Jekyll:
    Update your _config.yml file to include the custom PageFind plugin:

    plugins: - jekyll-sitemap - jekyll-gist - jekyll-feed - jekyll-toc - kramdown - jekyll-sitemap - ./_plugins/pagefind.rb

  3. Create the PageFind Plugin:
    Create a new directory named _plugins at the root of your Jekyll project and add a file named pagefind.rb with the following content:

    Jekyll::Hooks.register :site, :post_write do |site| system("pagefind --source '_site'") end

  4. Configure PageFind:
    Create a file named pagefind.yml in your root directory to configure PageFind’s behavior:

    source: _site bundle_dir: _pagefind split_pages_on: "h2"

  5. Set up GitHub Actions:
    Create a new file named .github/workflows/deploy.yml in your repository with the following content. This setup will install PageFind during the deployment process, eliminating the need for a local installation:

    name: GitHub Pages on: push: branches: - main # Change this to your default branch if it's not 'main' jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v2 - name: Setup Ruby uses: ruby/setup-ruby@v1 with: ruby-version: '3.0' - name: Install Jekyll and Bundler run: | gem install jekyll bundler bundle install - name: Install Node.js uses: actions/setup-node@v2 with: node-version: '14' - name: Install PageFind run: npm install -g @pagefind/core - name: Build site with Jekyll run: bundle exec jekyll build - name: Run PageFind indexing run: pagefind --source _site - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: $ publish_dir: ./_site

#Explanation and Key Considerations

  • _plugins/pagefind.rb: This plugin ensures that PageFind indexes your site content after each build.
  • pagefind.yml: This file configures PageFind, specifying the source directory, output directory, and content splitting behavior.
  • .github/workflows/deploy.yml: This workflow automates the entire process, building your Jekyll site, running PageFind indexing, and deploying the final output to GitHub Pages.
  • pagefind-entry.json: This file, generated by PageFind during indexing, is crucial for the search functionality. Ensure it’s correctly generated and located in the _pagefind directory.
  • CSS Customization: Include and customize the pagefind-modular-ui.css file to style the search interface according to your website’s design.
Previous
Next