{"id":13707808,"url":"https://github.com/capnfabs/paperesque","last_synced_at":"2026-01-24T20:34:38.838Z","repository":{"id":42936102,"uuid":"210030800","full_name":"capnfabs/paperesque","owner":"capnfabs","description":"A lightweight theme for Hugo (gohugo.io)","archived":false,"fork":false,"pushed_at":"2025-04-23T06:47:13.000Z","size":1417,"stargazers_count":71,"open_issues_count":4,"forks_count":18,"subscribers_count":2,"default_branch":"mainline","last_synced_at":"2025-05-03T00:03:19.938Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://themes.gohugo.io/paperesque/","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/capnfabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-09-21T17:59:19.000Z","updated_at":"2025-04-23T06:47:16.000Z","dependencies_parsed_at":"2024-06-06T11:01:48.600Z","dependency_job_id":"78c27cbc-2630-4d84-b610-09551f383c39","html_url":"https://github.com/capnfabs/paperesque","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnfabs%2Fpaperesque","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnfabs%2Fpaperesque/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnfabs%2Fpaperesque/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnfabs%2Fpaperesque/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capnfabs","download_url":"https://codeload.github.com/capnfabs/paperesque/tar.gz/refs/heads/mainline","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252621784,"owners_count":21777867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T22:01:44.325Z","updated_at":"2026-01-24T20:34:38.788Z","avatar_url":"https://github.com/capnfabs.png","language":"CSS","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"# Paperesque\n\nA lightweight [Hugo](https://gohugo.io) theme with a couple of neat tricks.\n\nYou can see it in action on [capnfabs.net](https://capnfabs.net).\n\nHere's what makes it special:\n\n- Has a shortcode for resizing images to fit the page, _and_ tools for removing originals from the output\n- Footnotes turn into margin notes when there's enough space.\n- Tools for editing and controlling publication:\n  - Visual differentiation for drafts\n  - The ability to \"mostly hide\" pages so that they're only accessible by knowing the URL.\n\n## Install\n\n### git subtree (easiest!)\n\nCopy the files into your repo using `git subtree` (this is way easier to use than submodules; [here's an explainer](https://www.atlassian.com/git/tutorials/git-subtree)):\n\n```sh\ngit subtree add --prefix themes/paperesque https://github.com/capnfabs/paperesque mainline --squash\n```\n\nThis will add a commit to your repo with everything ready to go. You'll probably want to modify parts of this theme for your own usage! Subtree makes that easy, because you've just copied the code into your repo ✨\n\n### git submodules\n\nIf you're sure you want to use git submodules:\n\n```sh\ngit submodule add -b mainline https://github.com/capnfabs/paperesque themes/paperesque\n```\n\n### Select the theme in your `config.toml`\n\nAdd / Modify the `theme` field in your `config.toml` for your hugo site:\n\n```toml\ntheme = \"paperesque\"\n```\n\n## Using Features\n\n### Homepage\n\nYou've got two options for the homepage:\n\n#### 1. A custom list of links.\n\n**Example**: see [examples/1-with-homepage-menu](examples/1-with-homepage-menu/).\n\nThis was the _only_ thing supported until Dec 2022-ish.\n\nSee the [example readme](examples/1-with-homepage-menu/README.md) for details on how to implement this.\n\n#### 2. A section + custom content in a sidebar.\n\n**Example**: see [examples/2-with-homepage-sidebar-content](examples/2-with-homepage-sidebar-content/).\n\nThis is what's in use on capnfabs.net today. I like it much better.\n\nSee the [example readme](examples/2-with-homepage-sidebar-content/README.md) for details on how to implement this.\n\n### Links in the top-right corner\n\nThese are config driven! Add this to your `config.toml` (for example):\n\n```toml\n[[params.topmenu]]\n  name = \"about\"\n  url = \"about/\"\n\n[[params.topmenu]]\n  name = \"contact\"\n  url = \"contact/\"\n\n[[params.topmenu]]\n  name = \"rss\"\n  url = \"posts/index.xml\"\n```\n\n### Removing original images after resizing\n\nThe `fitfigure` shortcode is exactly the same as the `figure` shortcode, but it automatically resizes your images to fit the container, _and_ provides different resolutions for different DPIs (1x, 2x).\n\nWhenever you use this shortcode, the theme makes a mental note of the resource you specified.\n\nNow, you need to do some configuration if you want the originals to be removed from the output.\n\nFirst, add this to your site's `config.toml`:\n\n```toml\n[outputs]\npage = [\"HTML\", \"droplist\"]\n```\n\nNow, as part of your build process, run:\n\n```sh\n./themes/paperesque/buildscripts/drop-resources.py [hugo-output-directory]\n```\n\n(the Hugo output directory is usually `./public`).\n\nThat's it! Resized resources will be removed.\n\nThis is _off by default_ because it peppers your build output with `.droplist` files, and if you're not expecting them, it's going to be an unpleasant surprise.\n\n### Visual differentiation for drafts\n\nThis one's on, and can't be switched off. Drafts have an orange stripey background everywhere. You can't miss them.\n\n### Footnotes turn into margin notes\n\nThis is _on by default_.\n\nYou can switch it off site-wide by adding `disableMarginNotes = true` to your `params` in your `config.toml`, i.e.\n\n```toml\n[params]\ndisableMarginNotes = true\n```\n\nAlternatively, you can turn it off per-page by adding the `disableMarginNotes = true` to your front-matter for the page.\n\n### Make pages only visible / accessible by URL\n\nYou can prevent a page from being publicly visible (included in lists etc) by adding the following to your front-matter:\n\n```toml\nsitemap:\n    disable: true\nparams:\n    mostlyHidden: true\n```\n\n- Note that `sitemap.disable` is only available since [Hugo 0.125.0](https://github.com/gohugoio/hugo/releases/tag/v0.125.0), so ensure you're building with that if you're relying upon this feature.\n\n## Testing against the example site\n\nYou can build the example site with this theme with:\n\n```\ncd examples/[example]\nhugo serve --themesDir=../../..\n```\n\n## Hacking / Modifying the JS\n\nThe javascript in use (`assets/js/main.js`) is built from the `./js/` directory. Here are instructions for how to modify the JS:\n\n### Set up\nFirst, you need to [install the `yarn` package manager](https://yarnpkg.com/getting-started/install).\n\nThen, run:\n\n```sh\nyarn install\n```\n\nto install the required dependencies.\n\n### Dev builds\n\nRun:\n\n```sh\nnpx parcel watch\n```\n\nSimple as that!\n\n### Production builds (i.e. before you commit code / deploy code)\n\n```sh\nnpx parcel build --no-source-maps\n```\n\n### Other resources\n\n- The explanation for how a lot of this works is in [this blog post](https://capnfabs.net/posts/hugo-theme-exclude-processed-images/), so take a look there if you get stuck or want to borrow some of the ideas without grabbing all of them.\n- You can see who else is using this theme by [searching Github for `paperesque filename:config.toml`](https://github.com/search?q=paperesque+filename%3Aconfig.toml\u0026type=Code) (requires login).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapnfabs%2Fpaperesque","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapnfabs%2Fpaperesque","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapnfabs%2Fpaperesque/lists"}