How to Edit Shika Materials
If you are interested in making contributions, edits, and updates to our existing Shika na Mikono materials, you've come to the right place. The following is a step-by-step overview on how you can make edits both online and offline.
For online edits, you will use this program, <strong>Penflip</strong>. So to start,
- Create a username and password on Penflip
- Navigate to the <strong>Shika na Mikono</strong> progect page and click on the specific project you wish to edit
- Click on the Join Project box in the upper right hand corner. This creates your own "version" of the project, which you will make changes to, and later submit to the "master" version.
- Make changes, edits, additions, etc. and remember to save your work as you go by clicking the 'Save' icon on the left hand side.
- When you've made all the changes you want to save, click the Submit Changes box at the bottom right hand corner of the page. This will send all your edits to the "master" version for approval.
About editing documents on Penflip
Penflip is a way for multiple people to make changes to the content of projects, but have automatic uniform formatting across the entire document. In order to do this, a user uses a specific typesetting notation known as Markdown. It is a very simple to learn and use, so don't be intimidated by it. All you need to learn it is this <strong>cheatsheet</strong> or any other tutorial you find through a search engine.
You can add images into a document! Simply drag and drop an image file into the Penflip editor and move the image code to wherever you want it inline with the text.
Equations & Special Characters
Markdown will get you as far as regular document elements (headings, lists, bold, italics, etc.) but our Shika na Mikono documents have rampant use of chemical formulas, mathematic equations, and other symbols that you won't be able to reproduce using Markdown.
This program, Penflip, has the capability to combine Markdown with other markup languages (e.g. HTML, LaTex) to have all elements exist in the final exported document. For example, here in Shika, we routinely use MathJax to make nice-looking math and chemical equations and we use HTML to add in special characters, such as Greek letters, degree signs, etc.
If you add in HTML or LaTex into your Markdown text, it will process in when you 'Preview' your document (as long as the syntax is correct). The process is very intuitive with lots of practice.
It is difficult to just write LaTex equations out of nowhere without prior knowledge of its use, so the best way for a user to create an equation is to use a <strong>LaTex equation editor</strong>.
And search for special characters (e.g. ®, ∞, Σ ) on an <strong>HTML tutorial page</strong>.
Offline editing becomes a somewhat more complicated process, and requires additional software. We'll do our best to provide information for both Windows and Mac users.
- Download software for "connecting" Penflip and your computer. <strong>Github</strong> for Mac and <strong>SourceTree</strong> for Windows are our favorites.
- Go to the Github website and create a username and password to gain access. Use will use this login info on the Github App (for Mac) or in SourceTree (for Windows) later.
- Download a text editor (a word processing program special for coding). <strong>TextMate</strong> for Mac and <strong>MarkdownPad</strong> for Windows are our favorites.
For SourceTree on Windows:
Download the existing files, called a repository, by "Cloning from URL." The URL you will use is specific to the Penflip project you wish to edit. Navigate to the specific project page, copy and past the URL, and then add .git to the end. For example, the "git access" link for the main Shika manual is:
This would then download the .txt files series that make up the Penflip document to the specified path on your computer.
For GitHub on Mac:
- Create a new repository (the place where existing files will be downloaded on your computer) by specifying a path and folder name.
Select the repository, and click "repository settings." You will need to provide a "git access" link that is specific to the Penflip project you wish to edit. The git access link to copy and paste for the main Shika manual is:
Click "pull" under the Repository menu. This connects the app to Penflip and downloads the .txt files that make up the project.
To make edits (Mac or Windows)*:
- Go into the local repository where the .txt files are.
- Make edits to the .txt files as needed, and then SAVE each individual file once edits are finished. SourceTree and GitHub will track all the changes.
- Back in Source Tree or GitHub, you should now notice any changes that you have made. You can now "submit" these changes by creating a new "branch" (which creates your own "version" of the project).
- To submit, you will now "push" your changes back to Penflip, but this only updates your own "version," and not the "master."
- Login to the Penflip online editor, where you should see your recent offline edits ready to "Submit for Changes." Do this by clicking the icon.
*We are still uncertain on the exact way to carry out this process. These steps will be updated once we fully know what is required.