PageFind with Jekyll

• 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.