--- title: 'hello workflow' tags: resources, tech, plaintext, writing robots: noindex, nofollow --- Text workflow tools and resources ================================= Draft. Updated Sept 2018 ## Markdown ### Learn markdown [markdowntutorial.com](https://www.markdowntutorial.com) interactive online tutorial [markdownguide.org](https://www.markdownguide.org/getting-started)an introduction to markdown with guides to extended syntaxes etc. ### More resources Markdown comes in different flavours. Here is an overview: <http://brettterpstra.com/2015/08/24/write-better-markdown/> **Commonmark** is a project to standardise markdown syntax that will work across al flavours. <http://commonmark.org/> Here's the full specification: <http://spec.commonmark.org/> And here's a **long list of syntax variations** <https://github.com/commonmark/CommonMark/wiki/Markdown-Flavors> #### Markdown & footnotes ##### Footnote syntax [^label] [^label]: footnote content ##### Flavours of markdown which support footnotes [Multimarkdown](https://github.com/fletcher/MultiMarkdown/) [Markdown Extra](https://en.wikipedia.org/wiki/Markdown#Markdown_Extra) Used in mediawiki #### Some markdown editors **Any text editor whatsoever** is a perfectly good option. Specialised markdown editors simply give you conveniences like syntax higlighting so you can quickly see you are typing correct markdown that will display the way you expect in your output; Preview tools and pandoc integration etc. They range form the very simple to the highly complex and you can use more than one depending on the task at hand, your markdown is still just a text file. ###### In your browser [**Stackedit**](https://stackedit.io) - Browser based, can link with google drive. [**HackMD**](http://hackmd.io) - Online platform where several people can write on one markdown document at the same time. [**Cryptopad**](https://cryptopad.fr) - Similar idea to HackMD but also allows encryption and a drive type folder sturcture. [**Prose*](https://prose.io "title") Browser based editor for editing github files. ###### Closed apps [**Typora**](http://typora.io) Distraction free. Talks talks to pandoc. *Only free during beta.* [**Texts**](http://texts.io) Paid app for mac and windows geared toward single source publishing. [**iA writer**](http://ia.net) Very pretty, talks to dropbox, nice mobile app. **Marked2** Mac app widely reported as useful. ###### Open source & cross platform [**QOwnNotes**](http://www.qownnotes.org/) Ugly looking, and mainly designed for notekeeping and tasks, but very versatile. Has split at cursor and merge note features (like scrivener). And many other powerful features easily integrates with several sync options. Extensible with scripts. Can launch external editor (eg/iA writer) [**Atom**](http://atom.io) is very configurable to different workflows with a bit of setting up. Can work directly with Git and Pandoc using packages. It's target audience is coders, which can be a learning curve for peole not used to opening things up and reconfiguring them. So, whilst possibly not the simplest solution for any given component of your workflow, this is a powerful way to organise a lot of components together and create a customised setup for a big project or things you do frequently. ###### some useful packages for atom - **markdown-language** replaces builtin git flavoured markdown - **word count** how else you gonna brag to yerself? - **pandoc-convert** convert your markdown to all the things - **markdown writer** lots of extras for easy markdown - **markdown-preview-enhanced** wil preview footnotes and has scroll sync and other features - **git-plus** use git without the terminal - Various linters are available for markdown syntax, spelling, grammar etc to scrape the fluff off your text. - It is also possible to integrate pdf preview and other tools into Atom to do your research and writing all in one place. The more packages you add the more bloated your atom install may become. You can reclaim some start-up time by disabling language packages you will never use. ## Git Git is an open source version control tool that you can use to track changes in writing you do by yourself or with others. To track your own writing you just need git installed and to initiallise it inside the folder you wish to track. To use it collaboratively you will need to connect to, and interact with a remote repository. Github is a very popular service for storing remote repos but it is not the only option. Here are a few you may come across:- | Name | Notes | | -------- |-----| | Github | Private company, you can't install you own instance. Paid or academic access only for private repos, very popular and lots of tools for publishing. Many integrations. | | Gitlab | _Open source_, Yay, you can run it on your own server if you want, or use theirs, Unlimited private repos for free. More granular permissions for who to share edit access with than github. Fewer integrations. | | Bitbucket | Owned by Atlassian, unlimited private repos with free account.| | Keybase | Free service. Offers secure encrypted private or group repositories. Requires some set up.| It is worth doing a little research to pick a platform that suits your long term needs before starting a big project and it's important to know that there are plenty of options for collaborating privately if your work requires it. ### Learn Git [try.github.io](https://try.github.io/) 15 minute introductory interactive tutorial [swcarpentary.github.io](https://swcarpentry.github.io/) more detailed introductory tutorials [git for academic writing](https://swcarpentry.github.io/git-novice/)--from above. [hello terminal](https://hackmd.io/s/Hkey6EZtM) - get started with basic unix commands to access git and git help files ### Install git (Mac newbies) If you are new to git and the terminal and use a mac then installing github desktop is an easy way to get started. You do not need to connect with github if want to just use it for version control of your own writing. However when you do want to collaborate this will not workwith Gitlab, Bitbucket, Keybase or any other non github remote repos. It is an eay way to install git on your mac without installing xcode etc. after you have installed it you cna still use git normally through the terminal or via other tools such as Atom. ## Pandoc Pandoc enables conversion of you markdown into many other kinds of output such as PDF, ODT, DOC, RTF, HTML, LATEX, EPUB etc. - <https://en.wikipedia.org/wiki/Pandoc> - <https://github.com/jgm/pandoc> - <https://pandoc.org> ### Install Pandoc (Mac) - <https://github.com/jgm/pandoc/releases/tag/2.1.2> command line pandoc, - You will need another programme to use through GUI such as Atom with pandoc-convert package, Typora etc. - You may also need Basictex in the background for generating pdfs <http://www.tug.org/mactex/morepackages.html> #### Use/try pandoc online Do not use these to convert documents containing personal or sensitive data. - <https://pandoc.org/try/> - <https://devotter.com/converter> ## Integrating reference managers. - Zotero users can use: https://gitlab.com/egh/zotxt with pandoc - there are also various workflows with bibtex formats that can be use to connect various tools together. Zotero is an open source reference manager that integrates with your browser and you word processor. It can import your Endnote database. [zotero.org](https://zotero.org) It is stable and has a good community around it, that has built many plugins such as zotxt. Bibtex is another widely used open source reference manager which is integrated with Latex. #### basic example: * **In Zotero** * Install betterbibtex extension * set betterbibtex to the default format for quick copy * create a collection for your document * export the collection as bibliography.bib to the location where your writing lives (it should automatically update everytime you add an item, it will be referred to to generate bibliographic entries in your pandoc compile) * add items you are using for this document to the new collection * **In Atom editor** * Install packages: Pandoc convert, Markdown writer & Markdown Preview Plus * Set markdown preview plus settings toggle 'citations' and adjust filenames for .bib file and citation style if you are not using defaults. * **To cite** * Select item in Zotero and use quick copy shortcut to copy the bibtex citekey * In Atom, paste citekey into position you wish citation to appear * **To export** * Add a *References* heading right at the end of the document where the bibliography will be rendered. * Use pandoc convert from command palette to export in a variety of formats ## Publishing ### Documentation ### Websites ### Academic