Collaborative Community Publishing
The roadmap is intended to be a general overview of our plans. It will provide a high-level list of what we're thinking about, what we've prioritized, what we're currently working on, and what we've done. It is not intended to be an exhaustive or completely up-to-date list of features or projects. We use GitHub milestones in the main PubPub Repo to track specific sprints of work.
The easiest way to access the PubPub API is through the PubPub SDK.
You can find documentation about the PubPub API at https://pubpub.org/apiDocs, or https://<yourcommunityURL>/apiDocs.
If you have a specific bug to report, feel free to add a new issue to the PubPub Repo. Please search the issue list first to make sure your bug hasn't already been reported. If it has, add your feedback to the preexisting issue. For new bug reports, please fill out all the applicable parts of the bug report template before submitting.
If you have a feature request, idea, general feedback, or need help with PubPub, we'd love you to post a discussion on the PubPub Forum. As with bug reports, make sure to search the forum first to see if the community has already discussed your idea or solved your issue. If we have, feel free to join in on that ongoing discussion. Remember to be polite and courteous. All activity on this repository is governed by the Knowledge Futures Code of Conduct.
At the moment, PubPub isn't particularly well setup for outside contributors. However, we'd like to get to that point, and if there's a specific feature or idea from our roadmap or issue list that you're interested in working on, we'd like to hear from you. Please send a note to hello@pubpub.org introducing yourself and describing how you'd like to contribute.
User-facing documentation is a work in progress, and can be found at https://help.pubpub.org. If you're interested in helping contribute to documentation, we'd love to hear from you. Please send a note to hello@pubpub.org introducing yourself and describing how you'd like to contribute.
pnpm install
To run locally on a Mac, use Homebrew to install a handful of dependencies:
brew install pandoc poppler
(See Aptfile for a list of equivalent Debian packages to install)
pnpm dev
Navigate to localhost:9876
PubPub uses three main font families, plus CJK variants:
- Source Sans 3 — headers, titles, UI text
- Source Serif 4 — body text in pubs
- Outfit — landing page
- Noto Serif TC/JP/KR/SC and Noto Sans TC/JP/KR/SC — CJK content
All fonts are variable-weight woff2 files from Fontsource, hosted on S3 at assets.pubpub.org/fonts/<hash>/. The font files are not stored in this repo.
A single fonts.css on S3 contains all the @font-face declarations (~940 rules) for every font family. Each rule uses unicode-range subsetting, so browsers only download the woff2 slices for characters actually on the page.
The font CSS is loaded via <link> tags in server/Html.tsx (web) and workers/tasks/export/html.tsx (PDF exports), so the browser can start fetching it in parallel with other resources.
Files on assets.pubpub.org have a long TTL. To avoid cache issues, all font files live under a content-hashed directory (/fonts/<hash>/). The hash is derived from the sha256 of all generated files. If nothing changes, the hash stays the same and nothing gets re-uploaded. If anything changes, you get a new directory and new URLs automatically.
Old versions remain on S3 harmlessly — they'll just stop being referenced.
Run the upload script:
# Dry run — downloads fonts, generates CSS, shows what would happen, updates source files
scripts/upload-fonts-to-s3.sh --dry-run
# Real run — same as above, but also uploads to S3
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... scripts/upload-fonts-to-s3.sh
The script:
- Downloads fontsource packages directly from npm (nothing gets installed in the project)
- Copies all woff2 files to a staging directory
- Generates
fonts.csswith correctedfont-familynames and relativeurl()paths - Computes a content hash from everything in the staging directory
- Uploads to
s3://assets.pubpub.org/fonts/<hash>/ - Updates the font URL in
server/Html.tsxandworkers/tasks/export/html.tsx
After running the script, commit the updated source files. You need AWS credentials with write access to the assets.pubpub.org bucket.
To add or remove font families, edit the PACKAGES and CSS_SOURCES arrays in the script, and update client/styles/variables.scss to match.
To build and test components, we use Storybook. To run:
pnpm run storybook
Navigate to localhost:9001
pnpm run prod
Navigate to localhost:9876
The Latex Buildpack we are using allows a
texlive.packages file in the root directory to specify additional packages to be installed.
List of available packages (I think...
documentation on packages is a bit tough to find).
Can be useful
for understanding what's in collections. Not sure why it's so hard to find official documentation on
texlive packages available.
The client side code of PubPub does follow a Container/Component split as is common in React-based sites. The structure and difference between the two in this repo is not exactly as described in the preceeding article. For this repo, the following describes how containers and components are differentiated:
- Associated with a specific URL route
- One a single container is used on a given URL route
- Calls hydrateWrapper() to initialize React bindings after using server-side renered HTML for immediate display.
- Holds the ground truth data for a given view. Often the ground truth data is passed into containers as props through hydrateWrapper(), but in cases where the ground truth data is being changed, the container will hold ground truth data in it's state.
- All other non-container components :)
- Many components are used within a given URL route
- Can store it's own state if needed for UX functionality - but should always update the ground truth data held in its parent container.
- Can make it's own API requests when the functionality and layout of the pertaining request is contained within the single component. Though if this request influences the ground truth data, the component should be passed an updating function that allows it to update the ground truth data held in the container.
Before your first pull request, make sure to copy our .githooks into your .git directory. You can do this with:
pnpm run install-git-hooks
Preferred practice is to prefix commits with one of the following categories:
fix: for commits focused on specific bug fixesfeature: for commits that introduce a new featureupdate: for commits that improve an existing featuredev: for commits that focus solely on documentation, refactoring code, or developer experience updates
Thank you to these groups for providing their tools for free to PubPub's open source mission.
