Comparing an article written in AsciiDoc and Markdown.

article.adoc.txt

= Setup Textastic app to write AsciiDoc on iOS

:1: http://www.textasticapp.com
:2: http://feedback.textasticapp.com/topic/454769-swift-syntax-highlighting/
:3: https://github.com/zuckschwerdt/asciidoc.tmbundle
:4: https://github.com/zuckschwerdt/asciidoc.tmbundle/archive/master.zip

I’m writing my next technical book and course material with AsciiDoc. In Mac, there is plenty of options to write the AsciiDoc with syntax highlight. In iOS, I’ve searched many text editor until I find {1}[Textastic] app to supports the syntax highlight with plugin.

I followed this {2}[Textastic forum post] to install syntax plugin on the iPhone. Here is my specific steps for installing the AsciiDoc bundle.

1. In the Textastic app, create a folder named `#Textastic` in the root of the local files. You should see a special icon for the folder if it succeeds. Our target is to put the bundle of syntax highlight into this folder. The app will automatically treat it as a plugin.
+
image::logs/textastic-folder.png[]
2. I use the {3}[AsciiDoc TextMate bundle]. You can find the zip location at the `Download ZIP` button on the Github page. Copy the {4}[URL to the ZIP file]. The URL is at the following.
+
[subs="attributes"]
----
{4}
----
3. Open the URL in iOS Safari, it’s a zip file so Safari won’t open it directly. Instead, it asks you for the application to open it. `Open In` > `Copy to Textastic`.
4. The system switches to Textastic and it asks if you want to unarchive the zip file. Choose `Yes`.
5. After the app unzip the bundle. Go into `asciidoc.tmbundle-master` folder. Then you see another folder with the same name. Rename that folder into `asciidoc.tmbundle`.
+
image::logs/to-rename.jpg[]
image::logs/rename-bundle.png[]
6. Move the folder `asciidoc.tmbundle` into the `#Textastic` folder which we created at step 1.
7. Kill the Textastic app and re-launch it. Now you should see a syntax highlight when you open any AsciiDoc document.

article.md.txt

# Setup Textastic app to write AsciiDoc on iOS

I’m writing my next technical book and course material with AsciiDoc. In Mac, there is plenty of options to write the AsciiDoc with syntax highlight. In iOS, I’ve searched many text editor until I find [Textastic][1] app to supports the syntax highlight with plugin.

I followed this [Textastic forum post][2] to install syntax plugin on the iPhone. Here is my specific steps for installing the AsciiDoc bundle.

1. In the Textastic app, create a folder named `#Textastic` in the root of the local files. You should see a special icon for the folder if it succeeds. Our target is to put the bundle of syntax highlight into this folder. The app will automatically treat it as a plugin.

    ![](logs/textastic-folder.png)
2. I use the [AsciiDoc TextMate bundle][3]. You can find the zip location at the `Download ZIP` button on the Github page. Copy the {4}[URL to the ZIP file]. The URL is at the following.

    ```
    https://github.com/zuckschwerdt/asciidoc.tmbundle/archive/master.zip
    ```
3. Open the URL in iOS Safari, it’s a zip file so Safari won’t open it directly. Instead, it asks you for the application to open it. `Open In` > `Copy to Textastic`.
4. The system switches to Textastic and it asks if you want to unarchive the zip file. Choose `Yes`.
5. After the app unzip the bundle. Go into `asciidoc.tmbundle-master` folder. Then you see another folder with the same name. Rename that folder into `asciidoc.tmbundle`.

    ![](logs/to-rename.jpg)
    ![](image::logs/rename-bundle.png)
6. Move the folder `asciidoc.tmbundle` into the `#Textastic` folder which we created at step 1.
7. Kill the Textastic app and re-launch it. Now you should see a syntax highlight when you open any AsciiDoc document.


[1]: http://www.textasticapp.com
[2]: http://feedback.textasticapp.com/topic/454769-swift-syntax-highlighting/
[3]: https://github.com/zuckschwerdt/asciidoc.tmbundle
[4]: https://github.com/zuckschwerdt/asciidoc.tmbundle/archive/master.zip

Remark.txt

1. I like the AsciiDoc that uses `+` to connect paragraphs inside list item, instead of adding indent in markdown.
2. The URL example `:1:` in AsciiDoc looks similar to `[1]` in markdown. But actually `:1:` is a variable that can be used any where.
3. This is just a simple comparasion for a simple document. I find markdown is good enough for a short article writing. On the other hands, AsciiDoc is better for longer writings.

Very nice.

You can drop the numbers in the ordered list, unless you prefer to have them.

Whenever you change the subs on a listing block, I strongly recommend that you use the incremental subs so that you still get the benefit of escaping special characters and such.

[subs=+attributes]

TIP: Double quotes around values in block attributes are only necessary if the value contains commas or spaces.

In item 5, you need to put the list continuation between each image block. One way to save you from having to use the list continuation between each block is to move the content of the complex list item into an open (anonymous) block.

5. After the app unzip the bundle. Go into `asciidoc.tmbundle-master` folder. Then you see another folder with the same name. Rename that folder into `asciidoc.tmbundle`.
+
--
image::logs/to-rename.jpg[]
image::logs/rename-bundle.png[]
--

That way, you only ever need a single list continuation...to "attach" the open block.

Thanks :) Nice tips.