Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Guide to using Harlowe

I've been working on a guide to writing stories using the Harlowe format and have decided to release a first version.

Notes: The guide was created using Twine.
It only covers the basics at the moment. I'm planning on adding more complicated stuff.
I'm also planning to add a cookbook to show how to solve common problems.

If anyone has any comments, corrections or suggestions then let me know.


  • A brief look-through suggests this will be very helpful to people and I would have really liked it when beginning work in Twine/Harlowe. Kudos for all your work--it makes sense that Twine would be an excellent format for a guide on Twine. I hope you will keep going on it.

    Other than minor typos (which I'd be glad to point out), the beginning threw me a little bit.

    It says:
    "This is a site about creating interactive fiction using the Twine 2 program.

    "This guide soley uses the Harlowe story format, though there are others available. A list of formats is here" (with a link to "here.") (note: "solely" spelling.)

    Then on the next page it says:

    The default format and the one that this tutorial uses. The manual is here." (with a link to "here.")

    I felt that it was disconcerting to be taken right out of your Guide on the second link to the official documentation. At first I thought that was the extent of your Guide! Then, going back to your site, I noticed the link to your Guide in the header, and I was good to go from that point.

    In other words, I feel the natural flow of your links takes you out of your own Guide, which you probably don't want, and that the link to your Guide is not prominent in the header (fifth in line). Maybe I'd link the word "Guide" and capitalize it in "This guide solely uses…."

    That's what I noticed right off the bat. Otherwise, excellent effort!
  • I got confused by the same thing yeah. I thought "Where is the guide?" since it seemed to only have external links on the pages.
  • edited August 2015
    Same here: I think the actual guide should also be linked in the body of the landing page.

    Anyway, this guide is amazing and much needed.
    It would be great if you could also add more examples that users can try in their stories.

    EDIT: for example, a more detailed description of how to use the special passages, and anything about how to create passages that execute stuff (which makes it easier to work with variables).
  • Thanks for the suggestions. It would be better to have links to the guide on the main page, as well as the menu bar. Also I think it'd be clearer if I moved the link to the official docs, to the page about different story formats.

    I'm going to keep working on the guide. Writing it is a good way to learn all the different features.
  • Melyanna wrote: »
    a more detailed description of how to use the special passages
    Harlowe does not have special passages like SugarCube does (eg. Passages with special names), or do you mean the startup, header and footer tagged passages?
    Melyanna wrote: »
    create passages that execute stuff
    Could you explain what you mean by this, or are you talking about the Story Javascript editor?
  • greyelf wrote: »
    Harlowe does not have special passages like SugarCube does (eg. Passages with special names), or do you mean the startup, header and footer tagged passages?

    I mean exacyly those three.
    The guide currently has a paragraph that says:
    Harlowe has three types of special passage, which are given a tag of either, "startup", "header" or "footer"

    These passage is displayed before the first passage. It can be used to initialise any data the story needs instead of using the old pattern of starting with the initialisation passage which would then display the real start passage.

    These passages are displayed at the top of every passage.

    These passages are displayed at the bottom of every passage.

    debug versions
    There is a debug version of all of those passages: "debug-startup", "debug-header", "debug-footer". These work the same as the normal versions, but only display when playing in debug mode.

    I think it would be useful for Twine / Harlowe users to expand that subject with some practical examples of how these work.
    The current description tells exactly what the passages do, but there are many things one can achieve playing with those passages, I think examples would give a clearer idea of the possibilities.
    greyelf wrote: »
    Could you explain what you mean by this, or are you talking about the Story Javascript editor?

    I was thinking, as an example, to passages an author may want or need to create specifically to make sure that certain variables or macros work as intended.
    Sure, you can always set your variables directly in a specific passage (or in your startup passage), but you may want to have some logic or other kind of "background" operation in a separate passage.

    The available documentation seems to mostly cover basic usage of the Twine 2.0 / Harlowe functionalities. I think it would be nice if the guide could expand the subjects a little bit.
    Of course, users can always try things out, get creative, or look at the forum, but I do think that there is a bit of a gap in the documentation that this guide could fill.

    Sorry, I am still new to Twine so I don't think I have all the terminology right, hopefully I sound less like a very confused pidgeon now...
  • I agree. It's important to not only show how each element works, but also ways to combine those elements in order to produce different results. So I'm working on a cookbook help with that.
    Some of the cookbook examples make use of headers and footers, but I'm also going to improve the description in the special passages section.

    On a side note, I've added an auto generated index page. Which is neat.
  • I've uploaded a new version of the guide.
    The main changes are:
    Following suggestions here I've added links to the guide to the front page, and made external links more obvious.
    The parts about using the twine editor have been moved to a separate section.
    I've added an index
    I've added some macros which had been missing
    I've added a cookbook
    It's now possible to view the source code for any page (Including headers and footers)
    It's now possible to link to a particular passage: will go straight to the harlowe guide
    There's a link which gives the url for each passage
    I've added a sandbox will lets you try out Harlowe macros.

    If you spot any errors or typos or have any suggestions, then please let me know.
  • edited October 2015

    I was away so I only had time now to play with the new guide.
    Awesome job!

    I found a small issue in the cookbook/inventory: when I click on "Play example game", I get:

    You don't have permission to access /recipes/recipe simple inventory.html on this server.

    Additionally, a 404 Not Found error was encountered while trying to use an ErrorDocument to handle the request.

    EDIT: I hadn't yet tried all pages when I wrote this comment, but it appears that this happens with all of the examples in the cookbook.
    (I just tried the countdown one).
  • Thanks for spotting that. The file permissions for the example games hadn't been set correctly. They're all working now.
  • I'm doing some more work on the guide. However it seems to me that now the official manual has been redone, the guide part of the guide is redundant.

    I'm thinking the best thing would be to deprecate the guide and focus on things like the cookbook and example games.

    If anyone disagrees with this then let me know.
  • I agree.
    I love your guide and have used it a lot so far, but with the new guide being live, a cookbook and example games would be most useful.
  • I've been mucking around with how the cookbook works and now the address bar shows the full url, including the name of the passage. Also, due to the way I've achieved this, the browser back and forward buttons work. There is the downside that the undo/redo buttons no longer work, so I've hidden them till they can be fixed.

    It's been tested on Firefox and Chromium, and seems to be working okay. However I don't want to replace the old cookbook till it's been tested a bit more thoroughly. If anyone wants to try it out then it's at

    There are a couple of issues with Chromium:
    While the cookbook works online, if you download it and try to run it as a local file it fails. This is due to Chromium (and presumably Chrome) blocking the history api for local files. I plan to detect if the history api isn't working and going back to the old way of working in that case.

    If you do the following
    Go to the cookbook from another site
    go to one of the first pages
    click back twice to go back to the other site
    click forwards twice
    It produces a javascript error which breaks the cookbook. I'm not sure what's causing this to happen, especially since it doesn't happen on Firefox.
  • edited January 2016

    Minor issue - there is a spelling mistake in the cookbook's first page (
    Everything else.
    Should be Miscellaneous.

    Weird issue - this is somewhat similar to what you described in your post, but it happens to me on Firefox:
    1. go to Styling
    2. click "Adding a picture in a box"
    3. click "Play example game"
    4. hit the browser's back button twice
    5. the following error is displayed:
    Sorry to interrupt, but this page's code has got itself in a mess.
    window.onpopstate@ line 1500 > eval:163:5

    (This is probably due to a bug in the Twine game engine.)
    6. Nothing happens until the page is reloaded.
    This happened to me 3 times out of the 5 I tried to repro the issue.
    I didn't try with any other link, but let me know if I should.

    Just noticed another typo in the cycling link page of the cookbook.
    "Neutral" is spelled "Nuetral" throughout the page.
  • edited January 2016
    Thanks for pointing out those errors.

    When moving to a new page Firefox is supposed to keep a record of the whole state of the previous page (including any javascript) in a special cache called the bfcache. Chrome doesn't do this at all and it seems that Firefox doesn't always do it properly.

    This means that after moving to a different page and back again, the engine will have lost its list of visited passages, so any attempt to move between passages will cause the error that you're getting.

    Thinking about it a bit more it's pretty clear that when I was working on this I had a bad case of Jurassic Park syndrome. I was so busy thinking about what could be done, that I didn't stop to consider whether it should be done.

    Given the number of problems that interacting with the browser history causes (some which only happen intermittently or on certain browsers) I'd have to spend a lot of time keeping the site working, which would be better spend on improving the examples. So I'm going to abandon all the browser history code.

    Thanks for testing it.
  • edited February 2016

    I found an issue in the savee/load example of the coookbook.
    For the "loading when a player specified the name", you have the following example:
    (link-repeat: "Load game")(set: $name to (prompt: "Where to load the file from?"))(if: $name is "")[(set: $name to "saveslot")](loadgame: $name)]

    I believe one [ is missing, so:
    (link-repeat: "Load game")[(set: $name to (prompt: "Where to load the file from?"))(if: $name is "")[(set: $name to "saveslot")](loadgame: $name)]

Sign In or Register to comment.