User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

entwine [2016/05/11 23:47]
entwine [2017/10/09 20:39]
Line 1: Line 1:
-===== Entwine ===== 
-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://​|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.  
-<note tip> 
-This document assumes you want to use Entwine with Grunt. It's also possible to use Entwine on the command line by itself, if you're experienced with writing shell scripts. If you'd like to do this, follow the directions for installing Node below, 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://​​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, other popular task runners for Node, and no current plans to create them.  
-==== One-Time Setup ==== 
-As the title indicates, you only need to complete the steps in this section once on your computer. You will need to be connected to the Internet. 
-  - Download the LTS version of Node from [[https://​|the official web site]] and install it by opening the file you download. LTS stands for "​long-term support"​ -- it lags behind the most current version, but is better-tested. 
-  - Open a terminal window. 
-    - On Windows, make sure to do this by following this path of options from the Start menu: Start -> All Programs -> Node.js -> Node.js command prompt. Doing so will make sure that Node is properly available to you. 
-    - On OS X, open the Terminal application that's in the Utilities folder of your Applications folder. 
-    - On Linux, how you open a terminal window depends on what distribution you're using. On Ubuntu, look under Applications -> Accessories -> Terminal. ​ 
-  - Type ''​npm install -g grunt''​ and press the Enter key. This command asks npm -- short for the Node Package Manager -- to install Grunt for you. The ''​-g''​ part ensures that you'll be able to use Grunt anywhere on your computer; it's installed globally. 
-npm will print out text as it installs Grunt. ​ It's normal for npm to pause for a moment before printing any response, but not for more than a few seconds. It's busy searching for the files you'll need. When you see the prompt again after it completes, you're done. 
-==== Project Setup ==== 
-You'll need to do the steps in this section each time you set up a new project. This document suggests a simple folder structure for your project, but you can use a different one if you prefer. 
-  * **src** (short for //source//) will contain all your source files. That means Twine story files, images or other multimedia, and CSS and JavaScript files. 
-  * **build** will contain any intermediate files that need to be created during the build process. 
-  * **dist** (short for //​distribution//​) will contain the end result of the process, ready to be posted to a web site or otherwise made available to the world. 
-Given that, here's what to do. You will need to be connected to the Internet. 
-  - Create a new folder for your project. In these examples, we'll call it **my-project**. 
-  - Open a terminal window and go to this new folder with the ''​cd''​ command. 
-    - On Windows, the easiest thing to do is to copy the address of your folder from the address bar of an Explorer window, and place quotation marks around it. The resulting command should look something like ''​cd %%"​%%C:​\Users\You\Documents\my-project%%"​%%''​. 
-    - On OS X, try typing ''​cd''​ with a space after it, then drag your project folder onto your terminal window. The resulting command should look like ''​cd /​Users/​You/​Documents/​my-project''​. 
-    - On Linux, the easiest way to get there varies by your distribution. 
-  - Type ''​npm init -y''​ and press the Enter key. npm will create a file for you called **package.json** that we'll talk about in a second. 
-  - Type ''​npm install --save grunt grunt-entwine''​ and press Enter. npm will think for a moment, then install Grunt and Entwine for you. 
-  - Create a folder named **src** inside the project folder. We don't need to create **build** or **dist**, but it doesn'​t hurt. Grunt will eventually create them for us as needed. 
-    - You can do this from the terminal window by typing ''​mkdir src''​ and pressing Enter, or just create the folder the way you normally would. 
-If everything went correctly, you'll have three things in your project folder: 
-  * A folder named **node_modules**. npm uses this as a storage area for the packages you ask it to install. You can leave this as-is. 
-  * A file named **package.json**. This file records information about your project; most importantly,​ what software packages it needs to work. You can leave this file as-is too, as npm will update it for you. (If you peek inside, you'll see it mentions ''​grunt''​ and ''​grunt entwine'',​ which you installed in step 4 above.) 
-  * The folder named **src** you created in step 5. 
entwine.txt ยท Last modified: 2017/10/09 20:39 (external edit)