Merge changes from master into loren

loren authored
revision 1ef096ae7ea8465fc7d82c9bd287478f77054f65
# Penflip Basics

Some core concepts of Penflip to get you started:

### Projects

The project page is the headquarters for you and your collaborators - you can write new content, edit existing content, invite collaborators, have discussions, browse changes, see project activity, export your project, and more.

### Writing

You'll see 'Edit' buttons across the site. Clicking any of these buttons will take you into athe distraction-free 'writing mode'Penflip editor, similar to Google Docs and other writing tools. Everything is written with [Markdown]( For an explanation onTo understand why markdown is awesome for writing, [read this](

### Versions

Every project has a master version. Whenever you invite somebody to your project, a new version will automatically be created for them, and all of their changes will be made on their own version. When a collaborator is ready to submit their changes into the master version, they'll create a Merge Request.

### Merge Requests

A Merge Request is a group of changes to your project. All merge requests go into the master version. As the project owner, you control the merge requests: you can accept them, ignore them, and comment on them to suggest changes. When you accept a Merge Request, the master version of your project will be updated with those changes.


Still confused? Email for help!
# Project Types

There are two types of projects on Penflip:

### Book Project

A 'book' project has a collection of files. Each section or chapter is a separate file. When you export your project, the files will be combined and turned into a presentable book. With a new 'book' project, some files are generated to get you started:

- **About**: an introduction to your project
- **Contents**: the contents of your book, like a table of contents. Each new file you create will automatically be added to Contents.txt, but you can remove or rearrange them as necessary. Only the files listed in Contents.txt will be included in your project when it is exported.
- **chapter1**: a sample chapter that would be included in your book

Through 'edit mode', y
. You can create new files/chapters as needed for your project.

A 'book' project also comes with a 'discussion board' where anyone working on the project can participate in conversations about the project. New conversations on different topics can be opened at any time, and old ones that are no longer relevant can be closed.

### Document Project

A 'document' project has a single file, much like a Google Doc or Word document. This type of project is ideal for short stories and collaborative essays. With longer papers (e.g. a PhD thesis), a 'book' project is recommended, so that the sections of the paper can be organized into different files.

Instead of a discussion board, a 'document' project has a simple unthreaded 'chat' feature.

### Public versus. private

When you create a new project, you can choose to make it public or private. A public project can be discovered by anyone, while a private one can only be seen by people who you explicitly share it with.

Still confused? Email for help!

# Versions and Tags

First, what is **version control**? If you aren't familar with the concept, vVersion control is simply means: a way to manage changes over time. If you've ever saved multiple versions of a document (like a *rough draft* and *final draft*), then you've hacked together your own version control system. Congrats! The problem with that is that it's fragile, inconvenientcumbersome and difficult to manage -, especially for long term projects with multiple collaborators.

Penflip handles all of this for you, so you can focus on writing.

### Versions

You can **think of a version like a copy of the project**. Versions change over time, and a Penflip project can have multiple versions. When you create a project, there's only a **master version**. The master version is the main version of the project, and only you can make changes to this version.

When collaborators join your project, a new version is created for each of them, automatically. For example, when your friend Tim joins your project, a new version will be created called 'tim'. When Tim makes changes to the project, those changes are only made on his version. The master version isn't updated until he submits his changes for approval.

When a collaborator edits your project, they will see a message like this:


### Submitting changes

After a collaborator makes changes on their version, they submit them for your approval, describing the changes they've made:



### Accepting changes

As the project owner, you will be notified of submitted changes via email, with a link to view the changes. From there, you can choose to accept or ignorereject the changes. If you accept the changes, the master version of the project will be updated with the new changes. If you reject the changes, they'll be discarded (but stored in an alternate version for archival purposes).

This is convenient because you can send a project link to your peers, request feedback, and only integrate the feedback you want to accept - all with the click of a button, in the browser.

### Tags

When you're editing your project, you can create tags. You can **think of a tag like a checkpoint or reference point** - marking a project in its current state at a specific time. For example, after you've released the first version of a book, you can create a 'version1' tag. You can continue making updates and changes to your book, but you can always go back to 'version1' to see how the book looked at that time.

Create a tag by clicking on the 'Save' icon while editing, then typing a tag name under 'Tag this version':


### Viewing versions and tags

On a project page, you see the master version by default. You can switch to any version or tag using a toggle in the bottom right corner. You can also download the project with any version or tag after you've switched.


*Note: this will not display unless there are multiple versions or tags.*

# Publishing Overview

Penflip projects can be converted and downloaded with a single click, turning a collection of text files into a beautiful compilation.

You can download any project you have access to, including both public and private projects, by clicking **Download** from the project page.

### Export formats

The following formats are currently supported: `.pdf`, `.docx`, `.epub`, `html`, and `plain text`. You can also download the full source of a project, which includes all project files and folders unaltered.

### Organizing contents

Files can be reordered by dragging and dropping in the editor sidebar, which represents how they will be displayed on the project page as well as in downloads.

Working offline? See [organizing contents offline](

### Exclude files from publishing

Sometimes you may want to exclude a specific file from the published compilation - for example, an unfinished chapter, or maybe a notes file. To exclude a file, simply click the eye icon beside the filename in the Penflip editor. Hidden files can be edited, but will not be displayed outside the editor.

![exclude files](

### Downloading alternate versions

By default, the master version of a project is compiled when downloading, but you can download alternate and past versions. To do this, view any [version or tag]( for a given project by selecting accordingly from the project page, as seen in this screenshot:


Clicking **Download** while viewing a particular version or tag will compile and download the project with the current selection. If you tag your releases (_v1_, _v1.5_, etc), you can download those past releases at any point in time.
# Working Offline with Git

Internally, Penflip uses [Git]( to manage versions, changes, and merges. By using Git or a Git-enabled tool, you can sync writing projects on your computer with Penflip. This allows you to work offline (using any text editor you want), then _push_ your changes to Penflip with a single click.

### Using command-line Git

If you are familiar with using Git from the command-line, you can have at it. The clone URL to use is available from your project's "Settings" page.

If you want to work offline with command-line Git on a version of another's project, here are some pointers to make it work:

1. Get the clone link of the project. This is the link you see on top of the page of the project + .git. For example with this project you do

git clone

2. Work locally
3. Push to your version branch, for example user `loren` would do

git push origin master:loren

### Using the GitHub desktop app

_Note: I'll be using the Mac app here, but the steps should be similar for the Windows app._

**1) Download and install the GitHub desktop app**

For Mac:

For Windows:

**2) Create a project on Penflip**

If you don't have a project yet, create a project here:

**3) Download your project**

You can download your project and add it to the GitHub app at the same time.

For Mac, type this in your browser:


For Windows, type this in your browser:


Make sure to include the full link to your Penflip project. For example:


The GitHub app will open. Select where you want to download your project to, and click 'Clone'.


You now have a copy of your project on your computer, including the full history of changes you (and your collaborators) have made.


**4) Make changes**

Your project is now on your computer like any other file or folder. You can make changes using and text editor. Here, I'm using textmate.


**5) Sync changes with Penflip**

The following steps are done through the GitHub app.

Switch to the 'Changes' tab:


Turn on 'Commit & Sync' (square toggle switch):


Type a description of your changes in the 'Commit summary' box:


Click 'Commit & Sync':


**6) Done!**

Verify that your changes have been synced with Penflip by looking at your project page.


Still confused? Email for help!
# Organizing Contents

In the web editor, you can organize the contents of your book via a drag and drop interface. This is obviously not available if you're working offline. Instead, you'll notice a `Contents.txt` file (hidden in the Penflip web editor), which achieves the same goal: displaying and organizing the contents of your book.

The Contents.txt file should contain a list of files to be included in your compiled book. The structure is simple: list one filepath per line. You can add, remove, or rearrange filepaths as necessary. Only the files listed in Contents.txt will be included in your project when it is exported.

An example Contents file:


Filepaths are case-insensitive.