===== Entwine Guide =====

Entwine is a tool that makes building large stories with Twine 2 easier. It's a good fit if you would like to:

  * Combine multiple stories in Twine into one single story
  * Include many external resources with your story -- i.e. images, video, or audio
  * Edit CSS or JavaScript files from an external editor, instead of using Twine's built-in one

Entwine is a command-line tool that integrates with [[http://http://gruntjs.com|Grunt]], which is a tool that automates repetitive tasks. If you don't have experience with Grunt or the command line, this can feel intimidating. It will take some setup work to use Entwine, but this document will guide you through it, and once you're done, your project will be able to build itself automatically as you make changes to its sources. That is, you'll be able to edit an image or change a passage and your project will automatically rebuild without you having to even choose Publish to File in Twine. For large projects, this tradeoff can be worth it.

==== First Things ====

Please go through these sections in order. These cover the basics of using Grunt, and act as a foundation for later sections.

  * [[One-Time Setup]]\\ There are a few steps you'll need to complete the first time you use Entwine.
  * [[Setting Up a Project]]\\ How to set up a project folder for use with Entwine.
  * [[Understanding Grunt]]\\ A primer on how Grunt works.

==== How-Tos ====

Feel free to pick and choose from the sections below according to what seems relevant to your needs. These are written so that they can be read in any order.

  * [[Combining Several Twine Stories Into One]]\\ If you'd like to segment your story into individual Twine stories.
  * [[Incorporating External CSS and JavaScript]]\\ Placing this content into external files.
  * [[Working With Images, Video, and Sound]]\\ Marshalling these resources into a story.
  * [[Publishing A Twine Story As A Desktop App]]\\ Making a standalone application from your Twine story.

<note tip>
This guide assumes you want to use Entwine with Grunt. If you're experienced with shell scripting, it's also possible to use Entwine on the command line by itself. To do this, follow the directions for installing Node in [[One-Time Setup]], then run ''npm install -g twine-utils''. After that completes, running ''entwine %%--%%help'' will acquaint you with the direct command-line interface, and the [[https://github.com/klembot/grunt-entwine|Grunt Entwine task's documentation]] also provides more information as to what the options do.

There is no Entwine plugin for Gulp or Brunch, which are other popular task runners for Node, and no current plans to create them. 
</note>