PubSweet How to Build a Publishing Platform Table of Contents About this Book 4 Introduction to PubSweet 7 What is PubSweet? 8 Examples of platforms built with PubSweet 12 Before you jump: things to know up front 17 Platform Design 21 Designing workow 22 PubSweet, workow and workspaces 24 Workow Sprints 28 eLife case study 36 Hindawi case study 39 Europe PMC case study 41 A general model 43 Technical Architecture 46 Architecture overview 47 Why did we choose our technical stack? 53 Getting started with PubSweet 57 Install PubSweet and set up an app 58 Conguring a PubSweet app 64 PubSweet Components 71 What are components? 72 How do you create a component? 76 How do you use components? 81 Authorization and Permissions 85 Why Authsome? 86 How to use Authsome 88 Theming 94 Using themes with PubSweet 95 Advanced theming 102 Deployment 107 Deployment essentials 108 CI/CD pipeline 110 Development Help 118 Where can I ask questions? 119 How can I debug? 121 Contributing to PubSweet 123 Testing 126 The Future 130 Where are we going now? 131 Glossary 134 Colophon 136 About this Book This book was written to help you use PubSweet to build the publishing platform of your dreams. It was written by the Coko community with the hope that you will nd it useful and join us in our eorts to liberate the scholarly publishing community from outdated workows and expensive proprietary soware. First a word on the Coko Community and the origins of PubSweet. Coko is short for the Collaborative Knowledge Foundation, co-founded by Kristen Ratan and Adam Hyde. Soon aer the Coko start up, Jure Triglav was em- ployed to start building the open source PubSweet toolkit for building pub- lishing platforms. This was at rst a lonely aair until eLife and Hindawi joined at the same time. Both organizations wished to join the eort to im- prove PubSweet so they could build their own journal publishing systems. That moment was the start of the Coko community and from there it has grown to include many other organizations including EBI, Wormbase, per- haps soon the Organization for Human Brain Mapping, and others. The Coko community, sometimes refered to as the PubSweet community in this book, is a vibrant and growing group of people enthusiastic about building better publishing workows and a better future for scholarly publishing. The Coko community wrote this book! Who should read this book? This book is targeted at a wide range of readers within the publishing in- dustry on both the product and technology sides: funders and strategic stakeholders making technology or budgeting decisions, project managers, designers, and soware engineers. Those in non-technical roles will get the most from the rst two sections, Introductıon to PubSweet and Platform Desıgn and the last on The Future of PubSweet: these sections set out the business case for adopting PubSweet and describe how your organization can set about re- designing or optimizing its workow. The more technically minded will PubSweet 5 benet from the central sections on Technıcal Archıtecture, Get- tıng Started Wıth PubSweet, PubSweet Components, Themıng, Deployment and Development Help. Of course, for anyone with sucient time, we recommend reading everything! Acknowledgements The book was written over three days using the Book Sprint methodology. We wish to thank Barbara Rühling, our facilitator from Book Sprints (http:// www.booksprints.net) for guiding us through this process and making all this hard work feel like fun. Also thanks to Henrik, Agathe, Raewyn and the rest of the Book Sprints crew who worked behind the scenes to make our work look great! Participating in the Book Sprint were Yannis Barlas (Coko), Bogdan Co- chior (Hindawi), Nick Dueld (eLife), Samuel Galson (eLife), Yuci Gou (EBI), Audrey Hamelers (EBI), Peter Hooper (eLife), Adam Hyde (Coko), Christos Kokosias (Coko), Tamlyn Rhodes (eLife), Paul Shannon (eLife), Julien Taquet (Coko), Alex Theg (Coko), and Jure Triglav (Coko). Thanks also to all the wonderful folks at Hindawi, eLife and EBI who generously made the time available for their teams to participate. The book was written about PubSweet using Editoria, a book production platform built on top of PubSweet, as envisioned by founders Erich van Rijn of University of California Press and Catherine Mitchell of California Digital Library. Editoria was also made possible by a generous grant from the Mellon Foundation. We are eating our own dog food. Because Editoria is so great, we could output the content to epub and book- formatted PDF immediately… zero to printed and electronic book in 3 days… amazing. Book Sprints + Editoria = the best! We also wish to thank the Shuttleworth Foundation for their generous support of Coko's co-founder Adam Hyde, and for the PubSweet Book Sprint. 6 About this Book Lastly, this book is dedicated to Alexis since he couldn't be here for the Book Sprint and yet the book was written with Editoria, and he wrote Edi- toria. It deserves a photo… Introduction to PubSweet Dixit, et ante tulit gressum, camposque nitentis desuper ostentat; So saying, he strode forth and led them on, Till from that vantage they had prospect fair Of a wide, shining land; Aeneid VI, 677-8 1 What is PubSweet? PubSweet is a free, open source framework for building state-of-the-art publishing platforms. PubSweet enables you to easily build a publishing platform tailored to your own needs. It is designed to be modular and �exi- ble. PubSweet consists of a server (“back end”) and client (“front end”) that work together, and both can be modi�ed and extended to add functionality to the system. PubSweet is being used for book publishing, academic journal produc- tion, and micropublication platforms by a growing number of established academic organizations including the University of California Press, eLife, Hindawi, California Digital Library and others. Each of these organizations is building their custom platform using Pub- Sweet, and contributing reusable open source components back to the com- PubSweet 9 munity. By drawing on this growing library of components, PubSweet can be used to rapidly create bespoke publishing systems. If the existing compo- nents do not completely meet your needs, you can focus development on building new components to provide just the new functionality required. If someone has built an entire publishing platform which you like (for ex- ample, Editoria or xPub), you can use it as-is, or replicate then extend it, us- ing your own ideas and components with minimal eort. Why does PubSweet exist? Today most of the publishing systems are “big box” platforms built years ago when the world of publishing was dierent. They have not evolved at the same rate as users' needs and are largely just data stores that track rather than enable or manage workow. Most of these systems are also ex- pensive, monolithic, and proprietary, so it is very dicult to change them to meet your organization's needs. Inevitably the reverse happens and you must change your organization to meet the prescriptive worldview of the soware. The PubSweet community believes that soware should be work- ing for us, not the other way around. When using o-the-shelf soware, changing a publisher's workow means changing their organization or switching platform vendors. Both op- tions are slow and expensive, making them undesirable. In the past, this has meant that the publishing sector has not been able to fully embrace the lat- est technological developments (for example, the web) or experiment and innovate in their workows. When you cannot own or control your own tools, you have little say in what those tools allow you to do; consequently, you become subject to them, losing control of your publication process. This lock-in can be avoided by giving the ownership of the tools back to publishers. PubSweet is built to do just that - it is an open source frame- work for building publishing workows. This means you can build the workows you want without compromising and continually update and op- timize them in the future. What are the bene. ts of PubSweet? PubSweet is free Open Source soware, so you don't have to pay to use it. You can modify it as much as you like, and use it for any purpose, including 10 What is PubSweet? commercially and for-prot. The license (a popular and permissive open source licence called the MIT license) grants a perpetual right to use Pub- Sweet in this way forever. Thanks to the focus on modularity, you can extend PubSweet with com- ponents. You can add new components, extend existing components, or re- compose a set of components on both the front end and back end as much as you like. You can leverage the existing components contributed to the community to lessen your development time and speed up your delivery. Assemble your own PubSweet platform PubSweet is web native so you can bring your workow to the web. Bring your whole workow, not just your published articles, into the web, the most powerful collaborative workow instrument of our time. PubSweet 11 Lastly, one of the most powerful reasons to use PubSweet is the Coko community. The ever-growing community of organizations building with and using PubSweet leads to a richer ecosystem with more components to draw from, and more resources to help you build your platform. By working together with the community, you can share the eort to produce new and exciting features, or reuse what someone else has built. Soware that is al- ready in use is likely to be more robust, free from defects, and well-adapted to real users.