Skip to content

Latest commit

 

History

History
218 lines (140 loc) · 9.86 KB

README.md

File metadata and controls

218 lines (140 loc) · 9.86 KB
Raw
layout permalink title description image lightbox toc code_highlighter
page
/theme
Papicu
A minimalist Jekyll theme with text-centric layout. Features dark mode, KaTeX, Sidenotes, Chart.js, Lightbox, TOC, etc.
true
true
true

Papicu

Papicu is a minimalist Jekyll theme.

It's been heavily inspired by Clio, another Jekyll theme. In fact, Papicu is basically a fork of Clio. I put it together to meet my own needs. But, if you like it, Papicu is free to use and modify. The source code is available at github.com/lucasrla/papicu.

Try the live demo at papicu.netlify.app.

What's inside?

Home Page (light mode) Home Page (dark mode)

Main features:

  • Dark / light mode
  • Privacy-conscious analytics (not Google Analytics)
  • Support to KaTeX
  • Support to Chart.js interactive charts
  • Support to sidenotes (a.k.a. margin notes)
  • Support to table of contents (TOC)
  • Support to deep anchor links
  • Support to lightbox for image zooming
  • Expandable & collapsible content
  • Lazy-loaded, responsive YouTube embeds with 16:9 aspect ratio

Papicu also includes:

  • A homepage that displays a brief introduction and the most recent blog posts in reverse chronological order
  • An about page located at /about/
  • A few sample blog posts
  • An RSS feed

Performance-wise:

Setup

Option A: use jekyll-remote-theme

First, have a Jekyll website/blog set up on your local machine.

If you are new to Jekyll, get familiar with it first: jekyllrb.com/docs.

  1. Add the following to your Gemfile

    gem "jekyll-remote-theme"
gem "katex", github: "lucasrla/katex-ruby"
gem "kramdown-math-katex"

  2. Install the gems by running on terminal

    bundle install

  3. Add the following to your _config.yml

    markdown: kramdown

kramdown:
  parse_block_html: true
  math_engine: katex

plugins:
  - jekyll-remote-theme

remote_theme: lucasrla/papicu

  4. By default remote_theme: lucasrla/papicu points to HEAD, the latest commit of Papicu. Optionally, you can refer remote_theme to a specific commit, tag or branch:

    remote_theme: lucasrla/papicu@1316b145a02c610347b9172da3d2feba32aaf595 # pointing to commit: https://github.com/lucasrla/papicu/commit/1316b145a02c610347b9172da3d2feba32aaf595
    remote_theme: lucasrla/[email protected] # pointing to (a theoretical) release tag v1.0.0 (please note that papicu has no releases yet)

  5. Now, run jekyll on terminal

    bundle exec jekyll serve

  6. Visit your website at http://127.0.0.1:4000

Option B: clone or fork this repository

If you are reasonably well-versed in Jekyll, clone or fork this repository and have fun.

Deployment

Issues with GitHub Pages

Unfortunately, Papicu is not compatible with the GitHub Pages standard workflow.

Why? Because, as of early March 2022, GitHub Pages (gem version 225) still uses Jekyll =3.9.0. Papicu needs Jekyll ~>4.1 to take advantage of slugified_categories (which we rely on for well-formed permalinks).

For those who are really interested, it is possible circumvent this limitation and run Papicu on GitHub Pages by using GitHub Actions. Read Jekyll's official guide on GitHub Actions for the details.

Netlify

Alternatively, sign up for an account with Netlify and deploy your website with them for free. We did that for our demo page: https://papicu.netlify.app.

If you need help, read A Step-by-Step Guide: Jekyll 4.0 on Netlify.

Usage

Running Jekyll on your local machine

First, you must install ruby and bundler locally. If you are on macOS, read the instructions at lucasrla.github.io/macos-setup/ruby.

Next, make sure bundler is configured with isolated environments by project:

bundle config set bin bin/
bundle config set path vendor.noindex/

Now, install Jekyll:

bundle install

# and then check if it has been installed properly
bundle info jekyll

Finally, run:

# We are passing `local` as `jekyll.environment` and checking for that inside `default.html` 
# to avoid sending analytics events when running locally.
# For more info: https://jekyllrb.com/docs/configuration/environments/

JEKYLL_ENV=local bundle exec jekyll serve

Post with examples

Each example post inside _posts/ demonstrates a few of Papicu features.

Have a look, for example, at the post titled Post containing demos of several features, and make sure you review its source code _posts/2021-02-01-post-with-bells-and-whistles.md as well.

Favicon generator

Try realfavicongenerator.net.

Metadata – JSON-LD, Open Graph, and Twitter Cards

Papicu takes advantage of jekyll-seo-tag to easily generate relevant metadata tags for search engines and social media.

Twitter Cards, Open Graph and JSON-LD (Google's guide) are supported out-of-the-box.

Please note that jekyll-seo-tag, as of v2.8.0, sets the Twitter Cards to summary_large_image only if there is an actual image referenced (say, at your post's front-matter). If there is none, it will default to summary. See, for instance, their issue #287.

License

Papicu itself is distributed under the terms of the MIT License. Plugins and third-party code have their own licenses. Check them out.

Credits and Acknowledgments

What does papicu mean?

Papicu means "narrow, elongated pond" in an indigenous language from Brazil. It is also the name of a neighborhood in Fortaleza, a city of northeastern Brazil.