5. About PubPub

What is PubPub? Why does it exist?

PubPub is an open-source platform for open access publishing of all kinds. It is a product of the Knowledge Futures Group, a non-profit building open infrastructure that serves the public good. From its beginnings as an in-house research-sharing platform at the MIT Media Lab, PubPub has developed based on the feedback of those who use it most and continues to be community-led. PubPub gives communities of all kinds a simple, affordable, and non-profit alternative to existing publishing models and tools. Using PubPub as a tool for civic engagement is an implementation the team is excited to support.

The PubPub roadmap is published for anyone to see, as is our codebase. We also invite users andthose curious about the platform to engage in our Forum.

Dictionary of terms

• Community: PubPub comprises many independent publishing communities. A community is the space you create and control for yourself and any collaborators. We choose the general word “community” to refer to these spaces so that community administrators can more specifically define what their community is for themselves. For some, their PubPub community will be a journal, for others a collection of books, while others will create communities for conferences or research notes.

• Page: a page on PubPub is a container of content. As such, it can both communicate information itself while often serving as entry point to other content within and outside of PubPub. Pages are designed by Community Admins using a series of different content block types.1

• Pub: a Pub is the most specific unit of content on PubPub. We’ve made up the word “Pub” because, much like with Communities, the definition and function of a Pub can change drastically from Community to Community. For example, a single Pub in one community can function as a book chapter (like here), while a pub in another can serve as a journal article (like here), and in a third Community a Pub may contain the video of a webinar (like here). Pubs as a unit of content are yours to create and share based on the goals and nature of your Community.

• Collection: a group of pubs within a community, collected using the platform’s “tags” feature. The parameters of a collection can be defined by each PubPub community, from a more traditional journal issue to an evolving collection of pubs on a subject. Some collections are thematic (example: “Robots”), while others are genre-specific and have metadata associated with them, like book ISSNs or journal issue DOIs.

• Admin: individual or individuals who manage a PubPub community. Admins can assume different roles and levels of access within a community.

• Collaborator: someone who contributes to the publication of a pub through many possible roles, such as brainstorming, editing, co-authoring, fact checking, project managing, and reviewing. These roles can be created and assigned for each Pub to credit collaborators based on the CRediT Taxonomy.

What are some characteristics that make PubPub unique?

• Collaborative editing

  Edit documents alone or in real-time with your team. Or, open your document to the public for large-scale collaboration, reading, and annotation of drafts (including in classrooms).

• Rich media documents

  Embed videos, LaTeX equations, references, interactive frames, and more.

• Context

  PubPub allows you connect your content to other content on the internet and to name the connection type (review, comment, preprint, translation, etc), providing greater context around your work. Whats more, these connection types are deposited to Crossref when you mint a DOI.

• Document History

  PubPub allows you to catalogue and link to published versions, as well as track the full edit history of a draft via a history slider.

  

• DOI minting

  PubPub provides up to 10 free DOIs per year and then charges $1/DOI after that. You can deposit them directly through PubPub, or work with us to use your own prefix.

  

• Credit

  The option to credit collaborators at every level ensures contributions throughout the publishing process are not forgotten. The ability to control access and privacy at each stage of the publishing process offers control and flexibility that suits many different types of publishing groups and helps add a level of transparency to your process.

• Dedication to longevity

  We're focused on long-term stable solutions for authors, reviewers, and publishers. We care about business models that are good for research, rather than good for advertisers or investors.

• Open source

  We operate in the open and all of our code is available. You can add a new feature yourself or fork the codebase entirely and host the platform independently.

Getting Started

The first thing to do to get started is to create a PubPub account and then create your own Community. Your community will serve as the space for your publishing and community engagement.

Setting up, structuring, and designing your community is one of the services the PubPub team offers, or you can do it yourself!

Site Design and Settings

Upon the creation of your community, you’ll find yourself on a homepage with some instructional copy and your community title. From here, click on “Dashboard” at the top right of your screen. A small dropdown will appear that includes the name of your community. Click on your community name.

This will take you to a dashboard, from which you can set your higher-level community-wide settings, as well as create new pages.

On the left hand sidebar, there are five options:

• Overview shows you collections, pubs, discussions, and reviews. You can search for a Pub (our word for what you might call a chapter, article, report, etc. based on what you’re publishing. As a brand new community with no content, this list won’t be relevant just yet.) in the bar marked “Filter Pubs & Collections.” You can scroll to see a complete list of Pubs, including discussions and reviews. You can create a Pub by using the button at the upper right. Collections is where you can add tags to content to better organize it on your site. Some collection tags, like books or journals, also have associated metadata. Collections will be more relevant later on when you have content in your community.

• Pages shows a list of all pages within the community. Pages are for static content (like an about page) and displaying your Pubs (like an issue page). From this view, you can edit, access, and see the visibility status of all your pages.

• Reviews are the way that authors (or anyone) who doesn’t have permission to publish directly to the community can add their content. They could be submissions, peer reviews, or more. Other community members can then discuss the reviews and decide whether to publish them.

• Members is where you can add members for your site. This list is determined by you and those who need to be involved in your project.(Members will need to create these accounts before you can add them using their name.)

Each member can have specific permissions as to what they can view, edit, and manage. Admins have wider permissions across the community.

• Settings will take you to your site’s master list of… settings!

Navigate to Settings.

Settings is where you can determine site-wide options, such as accent colors, your navigation bar, footer, and logo(s). It is also where you establish your homepage banner.

For freely-usable, high-quality images, we recommend Unsplash.com. Please credit photo authors when using their work.

The favicon image is used on the browser tab. The preview image is for social sharing cards.

Your “Public New Pub Button” will be toggled off. Turn this on if you would like all new visitors to be able to create content of their own on your community. There are ways to give specific people permission to do this, which we’ll describe later.

You have the option to show a navigation bar or not. If you’d like one, you can add and organize internal pages and links to external ones here. Please note: you must first create pages to organize them here on the navigation bar.

You have the option of showing a homepage banner or not. If you’d like one (most communities have a banner), this is where you can design it. We recommend playing around with all of the banner options and using the preview tool below them to see what they look like in practice.

There are countless combinations of ways you can design your banner. One feature, for instance, is the ability to include up to two buttons in your banner. Some OA books use this, for instance, to link to buying options for readers who are interested in purchasing a print copy. Others use it for a newsletter. Some do both!

Use the banner background option for an image that will fill up the header of your Community. The Knowledge Futures Group Notes community implements a banner background with centered text.

Use the banner image option for an image that will appear to the right of your banner. The book, Smart Enough City, implements this nicely.

Use the banner logo option for an image that will appear to the left of your banner. Goldsmiths Press implements this option well.

Social is where you can add links to any additional websites, social spaces, or ways to contact you. They are all optional.

Footer is where you can manage the content on the bottom of your community, from a logo or image to additional links.

Important Details

• URL (e.g., https://community-name.pubpub.org)2

• Community Name

• Description

• Social links

  • Website

  • Twitter handle

  • Facebook

  • Contact Email

Branding

Community Accent Colors (light/dark)3

Homepage Banner

• Banner Logo and Background (see also Image Specs)

• Banner Title & Text (if desired)

Header

• Header preferences (based on community accent colors) 

  • Header color (light or dark)

  • Header text (light or dark) 

  • Header logo (show/hide)

Image Specs (recommended)

Homepage

• Banner Logo (appears on the left or centered): 200*750px

• Banner Background (spans across): 1200*800px

• Banner Image (appears on right or centered): 600*600px

• Footer logo:  40*150px

Miscellaneous

• Favicon (browser icon) : 50*50px

• Header logo (used in the header bar): 40*150px

Navigation / Discoverability

Increase visibility of important content via the Navigation Bar4. Communities typically include a mix of the following pages:

• About

• Issues/Collections/Chapters (whichever theme fits your community)

• News or Events

• Editors or Staff

• Resources

• Submit

Tip: Add a drop down menu to nest navbar items as subpages.

Page Design

A Page on PubPub is a container of content. It can both communicate information itself while often serving as an entry point to other content within and outside of PubPub. Pages are designed by Community Admins using a series of different content block types. In the sections that follow, we’ll go over the page creation, design, and management processes.

Page Creation

From the Community Dashboard, select Pages and + Create Page

Create New Page options:

• Page Title: The title of the page that will show on PubPub, in search, and in social media previews. Required.

• Page URL: The slug of the URL of the page. Only letters, numbers, and dashes are supported. Required.

• Description: The description of the page that will show on PubPub, in search, and in social media previews. Optional.

Page Details

You’ll be prompted to edit the page details and adjust the layout immediately following the Create Page step. However, if you want to return to this step at a later time you can do so by accessing the Dashboard -> Pages -> and then select Edit page. It’s important to remember to click Save Changes save each time edits are made.

Details:

• Page Title: The title of the page that will show on PubPub, in search, and in social media previews.

• Description: The description of the page that will show on PubPub, in search, and in social media previews.

• Preview image: The default image that will display on social media and in search results that link to the page. Click the image preview or pencil icon to replace the image. Click the arrow icon to download the image. Recommended size: 500px x 500px. Default: none.

• Link: The slug of the URL of the page. Only letters, numbers, and dashes are supported. Warning: Changing the link will cause old links you have previously sent to collaborators to fail.

• Width: The width of the page elements on large screen sizes. Default: wide.

• Privacy: Whether the page is viewable publicly, or only by community admins. Default: private.

  

Page Layout

The next step in the Edit page process focuses on Layout. Click the add block button and select the block type you wish to add (block types are described below). Click the move up button to move a block up. Click the move down button to move a block down. Click remove to remove a block. When you are done making changes, click save changes.

Non-default blocks are blocks that have been pre-set with custom options.

Block Types

Pubs Blocks

Displays a filtered list of pubs in your community.

Options:

• Title: Displays a title for the block of pubs. Default: blank

• Filter by tag: Sets tags that will be used to filter the block of pubs. Pubs must have one or more of the selected tags set to be displayed in the block. If no tags are selected, all pubs in the community are eligible to be displayed in the block. Default: blank

• Limit: Sets the maximum number of pubs that will be displayed in the block. Default: Show all pubs

• Order: Sets a custom order for pubs in the block. To use, click the button and drag pubs from the available pubs section to the pinned pubs section. Pubs in the pinned pubs section will be displayed at the top of the block in the order set. If fewer pubs than the limit are in the pinned pubs section, the block will fill the rest of the slots from the available pubs list by the newest created pub. Default: blank

• Preview type: Sets the size of the pub preview displayed in the block. Default: large

• Preview elements: Sets which elements the block should display. Default: all

Banner Block

Displays a large title and, optionally, a submission or link button.

Options:

• Text: The large text that displays in the banner block. Default: Hello

• Color: The background color for the banner block. Default: #3275D8

• Align: Sets whether the text is aligned left or center. Default: center

• Size: Sets whether the block is constrained to the width of the page content or goes across the entire screen. Default: full

• Image: Sets the background image for the block. Click the image preview to replace the image. Recommended size: 500px x 500px. Default: none

• Banner button type: Sets whether the block contains a button, and if so, what type. Button text sets the text of the button.

  • Create pub: Adds a button that allows anyone to create a pub. Default pub tags field sets the default tags that will be assigned to Pubs created using the new pub button.

  • Create account: Adds a button that prompts readers to create an account.

  • Link: Adds a button that links to an external website. Link field sets the url that the button will link to.

Text Block

Displays richly formatted text.

Options:

• Text align: Sets whether text in the block is aligned to the left or center. Default: left

• Text formatting and multimedia options: see Pub Editor reference guide.

HTML Block

Displays arbitrary HTML code. Javascript is not supported.

Pages Block

Displays a filtered list of pages.

Options:

• Title: Displays a title for the block of pubs. Default: blank

• Set pages: Sets the order for pages in the block. To use, click the button and drag pages from the available pages section to the displayed pages section. Pages in the displayed pages section will be displayed at the top of the block in the order set. Default: blank

The PubPub Editor

To learn more about how to navigate and customize a new piece of content on PubPub, including uploading content, watch these two videos:

Pricing Tiers

There is always a completely free version of PubPub available for anyone to use. This is our “Independent” pricing tier, where we encourage people to contribute what they are able to—including $0.00. Paid tiers include additional support and features. The PubPub team also offers some production services to help you get started on the platform.5

Terms of Service

The PubPub Terms of Service are published here. If you have any questions about these Terms of Service, please contact help@pubpub.org.

How can I get in touch with the PubPub Team?

We love hearing from our users and potential partners! There are a few ways to communicate with us:

• The PubPub Forum: a place to get help and connect with other members of the community.

• Email: shoot an email to help@pubpub.org with questions and one of us will reply. Magical!

• Github: you can submit issues, bugs, enhancement requests, and ideas on Github.

How do I receive news about PubPub?

• Newsletter: Subscribe to our monthly newsletter! We won’t email you constantly or share your contact information. But we do let you know about new, creative things people are doing on the platform, updates and additions to our features, and a bit about what we’re reading and thinking about. Our Newsletters can also be found here.

• Twitter: we’re on Twitter! If you are too, give us a follow. We tweet to amplify the announcements and publications of the communities on PubPub, to let our followers know about platform updates, and to make connections between our work and the broader open knowledge and scholcomm space.