@@ -8,81 +8,54 @@ Sail is Hoon markup that’s used to render a web page with XML. But what makes
9Udon is a way to write content for the web. It's a minimalist markup language for creating and rendering text documents, with a Markdown-inspired syntax. It's integrated with our Hoon programming language, allowing it to be used as standalone prose in its own file or embedded inside a Hoon source file, in which case it will be parsed into a tree of HTML nodes using Sail.
9Udon is a way to write content for the web. It's a minimalist markup language for creating and rendering text documents, with a Markdown-inspired syntax. It's integrated with our Hoon programming language, allowing it to be used as standalone prose in its own file or embedded inside a Hoon source file, in which case it will be parsed into a tree of HTML nodes using Sail.
11−This document will be divided into two main sections: the Sail guide and the Udon guide. The Udon guide has two sub-sections that each walk you through a practical example. Also, you're encouraged to read the Getting Started section below, which applies to both Udon and Sail.
11+This document will be divided into two main sections: the Sail guide and the Udon guide. Also, you should read the Getting Started section below, which applies to both Udon and Sail.
13## Table of Contents
13## Table of Contents
15+- [Getting Started](#getting-started)
15- [Sail: A Guide](#sail)
17- [Sail: A Guide](#sail)
17- [Udon: A Guide](#udon)
19- [Udon: A Guide](#udon)
19−- [Udon: A Simple Blog](#blog)
21−- [Udon: A Static Site](#static)
23−## Getting Started
21+## Getting Started {#getting-started}
25Before starting with either Sail or Udon, make sure that your ship is
23Before starting with either Sail or Udon, make sure that your ship is
26−[mounted to Unix](https://urbit.org/docs/using/setup/)
24+[mounted to Unix](/docs/getting-started/booting-a-ship)
28−To host that output, your ship also has a web-server, called
26+To host that output, your ship also has a web-server that can be found at
29−[Eyre](https://urbit.org/docs/using/web/), that can be found at
30−`http://localhost:8080/` if it’s your first ship that’s running on the
27+`localhost` (default port 80) if it’s your first ship that’s running on the
31machine, `http://localhost:8081/` if it’s the second ship on that same machine,
28machine, `http://localhost:8081/` if it’s the second ship on that same machine,
32and so on. In the startup messages, a ship will tell you which HTTP port it's
29and so on. In the startup messages, a ship will tell you which HTTP port it's
35−The `/web` directory of the `%home` desk is served by default. You can change
32+Udon and Sail files are often run as independent files (`.udon` and `.hoon`
36−which desk you're serving by using the command `|serve` in the Dojo. If you
33+respectively), but for the purpose of this guide, we will run them out of the
37−have already created and mounted a desk named `%sandbox`, for example, you can
34+`frontpage.hoon` file located in the `/gen` directory. The default content of
38−switch to serving it with this command:
35+`frontpage.hoon` is Sail code.
44−The first time you serve a desk, `/web` will be included as default. After that,
37+To use `frontpage.hoon`, we use a `|serve` command like this one in your ship's
45−you will need to explicitly append `/web` to the desk you're switching to --
38+Dojo:
46−otherwise, you'll need to write `http://localhost:8080/web` every time you
47−navigate to your web-server. Newly served desks not automatically having `/web`
48−as their root directory is a bug.
50−To switch back to your `%home` desk and set `/web` as your root directory, run:
53−|serve %/web
41+|serve /test %home /gen/frontpage/hoon
56−We'll be serving the `%home` desk for the examples in this tutorial.
44+This command has three arguments:
57−
45+- The first is the URL we want to bind our site to. We chose `/test`, so the URL
58−### Rendering
46+we will find our site at is `localhost/test`.
47+- The second is the desk we want to serve. We will be serving from `%home` in
49+- The third is the file that we want to serve. In this tutorial, we will be
50+using `/gen/frontpage/hoon`, which refers to `frontpage.hoon`.
60−That server has access to source files located in `/<your-urbit>/home/web` and
52+Run the command `|serve /test %home /gen/frontpage/hoon`. Now navigate to
61−any sub-folders thereof. For the purposes of this tutorial, we will only be
53+`localhost/test` (or `localhost:8081/test` if your ship is on that port) in your
62−using files that are located in the `/<your-urbit>/home/web/pages` path.
54+browser, and you should see the rendered Sail.
64−There is an important distinction between these two paths. According to
56+**Note:** Important to remember that every time you edit a file in your ship's
65−`/ren/urb.hoon`, any file inside of `/web` or any of its sub-directories
57+pier (Unix directory), including `frontpage.hoon`, you need to run `|commit %home`
66−is put through a tree of renderers specified at `/ren/urb/tree.hoon`
58+to copy those changes to Urbit.
67−-- _except_ for files inside of `/web/pages`. All of the files in `/web` and
68−its non-`/pages` children directories have various operations on files, such as
69−wrapping your Sail the `html`, `head`, and `body` nodes. This rendering tool,
70−called simply **Tree**, also adds certain formatting polish, such as a sidebar
71−that lists sibling files in the same directory.
73−The `/web/pages` sub-directory is a unique case with its own rendering rules.
74−The Tree is not used when rendering files in this path. The existence of no tag
75−is inferred, and no special formatting is applied. Such simplicity is ideal for
76−introducing the basics of Sail. Any source file located in `/web/pages` must
77−produce a complete HTML node with "head" and "body" nodes as children.
79−Understanding the details of the rendering pipeline is not necessary to complete
80−this tutorial. But, if you are curious, you might find it illuminating to
81−explore the contents of the `/ren` directory.
83−So, if a Sail source file named `sailtest.hoon` is saved in your `/web/pages`
84−folder on your only running urbit process, you can view that source rendered
85−into a web-page at `localhost:8080/pages/sailtest/`.
87## <a name="sail"></a>Sail: A Guide
60## <a name="sail"></a>Sail: A Guide
@@ -122,14 +95,13 @@ It’s easy to see how Sail can directly translate to HTML:
125−Save the above Sail code in `/home/web/pages/firstsail.hoon`, and the above
98+You can test above Sail code by placing it
126−HTML code in `/home/web/pages/firsth.html`. Access the resulting pages by
99+under `^- manx` in your `frontpage.hoon` file, and then running `|commit %home`
127−navigating to `http://localhost:8080/pages/firstsail` and
100+in the Dojo. If you've already run the `|serve` command code from the first
128−`http://localhost:8080/pages/firsth.html`, respectively, in your browser. The
101+section, the new content should appear at `localhost/test`.
129−resulting pages should be identical!
131−It shouldn't be hard to see the similarities here. So let's go into more
103+It shouldn't be hard to see the similarities between Sail and HTML. So let's go
132−detail about what the differences are.
104+into more detail about what the differences are.
134### Tags and Closing
106### Tags and Closing
@@ -701,25 +673,30 @@ allowing it to be used as standalone prose in its own file or embedded inside a
701Hoon source file, in which case it will be parsed into a tree of HTML nodes
673Hoon source file, in which case it will be parsed into a tree of HTML nodes
702using Hoon's XML-templating syntax, Sail.
674using Hoon's XML-templating syntax, Sail.
704−This document is itself written in Udon, and its source file is of the
705−Udon `.udon` extension. As such, we use some `formatted text` to make
706−it clear what is and isn't code, and to display that code to you instead of
707−actually using its semantics for formatting.
709There are quite a few similarities between Udon and the
676There are quite a few similarities between Udon and the
710CommonMark standard, but there are enough differences that you shouldn't rely on
677CommonMark standard, but there are enough differences that you shouldn't rely on
711existing knowledge of the latter. Udon generally supports only one
678existing knowledge of the latter. Udon generally supports only one
712syntax for each type of HTML node it emits. Udon is also stricter than
679syntax for each type of HTML node it emits. Udon is also stricter than
713Markdown: some syntax errors will prevent the file from being parsed at all.
680Markdown: some syntax errors will prevent the file from being parsed at all.
715−We provide a few simple examples [here](#examples) of how to publish
682+## Testing Udon
716−Udon files using our web interface.
683+
684+Udon files use the `.udon` file extension, but for this entry-level guide, we
685+will use the `frontpage.hoon` method that we are already familiar with.
687+To test out Udon, put a `;>` under the `^- manx` in your `frontpage.hoon` file,
688+and then put all your Udon code under that `;>`. Then run `|commit %home`
689+in the Dojo. If you've already run the `|serve` command code from the first
690+section, the new content should appear at `localhost/test`.
718## Udon Syntax
692## Udon Syntax
720### Front Matter
694### Front Matter
696+> Note: The Front Matter section only applies to .udon files, and not the
697+frontpage.hoon testing method.
722−The first thing on your file is a chunk of code called the front matter. It
699+The first thing on a `.udon` file is a chunk of code called the front matter. It
723contains metadata about your page, such as date, title, and position relative
700contains metadata about your page, such as date, title, and position relative
724to sibling pages.
701to sibling pages.
@@ -1255,282 +1232,3 @@ Produces:
1256 <small>[reactive publishing intensifies]</small>
1233 <small>[reactive publishing intensifies]</small>
1260−## <a name="blog"></a>A Simple Udon Blog
1262−Publishing using Udon is really easy. It uses the file extension `.udon`. Here we'll create a very simple blog and publish our first posts.
1264−First, let's setup a desk to serve our posts from:
1267−|merge %site ~your-urbit %home
1270−Then let's mount that desk to unix:
1276−You should now be able to find a `/site` folder inside of your pier
1277−directory (either `comet/` or `your-urbit/`).
1279−To begin serving files from this new desk use `|serve`:
1285−First let's create the landing page for our blog. Create the file
1286−`site/web/blog.udon`:
1295−This is a simple blog I built on Urbit.
1297−;list(dataType "post");
1300−Try viewing this file at `http://localhost:8080`. Note that `8080` might be
1301−`8081`, `8082`, and so on, depending if those ports were being used when you
1304−The only special thing about this page is the `anchor/'none'` front-matter
1305−which simply turns off the Tree navigation. Normally Tree gives navigation
1306−controls for walking around the filesystem, but taking them away makes
1307−the page seem more like a landing page.
1309−The page looks pretty boring now. Let's add our first post. From
1310−unix run `mkdir your-urbit/site/web/blog; touch
1311−your-urbit/site/web/blog/post-1.udon`. (Currently [there's a
1312−bug](https://github.com/urbit/urbit/issues/321) that prevents empty
1313−directories from getting created, so we have to `touch` a file inside
1314−them first.) In `blog/post-1.udon` let's add some filler content:
1317−:- :~ navhome/'/blog'
1320− title/'My first post!'
1324−Is this a decentralized Medium? Let's find out.
1326−But first, how about a long quote from Paramenides:
1328−> True, he said; and therefore when ideas are what they are in
1329− relation to one another, their essence is determined by a relation
1330− among themselves, and has nothing to do with the resemblances, or
1331− whatever they are to be termed, which are in our sphere, and from
1332− which we receive this or that name when we partake of them. And
1333− the things which are within our sphere and have the same names
1334− with them, are likewise only relative to one another, and not to
1335− the ideas which have the same names with them, but belong to
1336− themselves and not to them.
1338−Good to get that out of the way.
1341−You should be able to view this file at:
1342−`http://localhost:8080/blog/post-1.udon`.
1344−You'll also notice that
1345−now the list of posts here: `http://localhost:8080/blog` has
1348−Here we use two pieces of front-matter worth noting: `type` and `navhome`.
1350−- `type` implies that the page has some special handling by Tree. When `type` is
1351− `post` we automatically put in the `date`, `title` and `author` when they're
1352− specified and add some styles.
1354−- `navhome` sets the path used by the home button (the circle in the top left).
1355− Since we want to send people back to the root of our blog, we set this to `/blog`
1357−Adding posts is as easy as dropping Udon files into the `blog/`
1358−directory. Pretty easy!
1362−Now let's enable comments on a blog post.
1364−First, turn comments on by editing the frontmatter in `post-1.udon`. Your
1365−frontmatter should look like this:
1368−:- :~ navhome/'/blog'
1371− title/'Blog comments'
1377−Now try loading your post here: `http://localhost:8080/blog/post-1.udon`.
1378−You should see a comments box at the bottom of the page.
1380−Try posting a comment! When you do you should see the following in
1384−+ /~your-urbit/home/55/web/blog/post-1/comments/~2016.6.20..23.20.54..0b88/md
1386−~your-urbit[tree]: receiving comments, ;join %comments for details
1389−Comments are written into the filesystem in the `comments/` folder
1390−relative to the page they're enabled on. When a new comment is posted
1391−a notification is also posted to the `/comments` `:talk` channel.
1393−Use `;join` to keep up with comments as they get posted:
1396−;join ~your-urbit/comments
1401−## <a name="static"></a>A Static Site
1403−Hosting a static tree of content is easy. Let's put together a really
1404−simple site for an imaginary Urbit meetup group.
1406−We assume you have at least followed the beginning of [our first
1407−examples](#blog) and created a desk called `site` and mounted it to
1410−Note: below we use Urbit's implementation of Markdown, [Udon](#udon).
1411−This markup language allows you to use snippets of Hoon code but not HTML.
1412−In particular, we use Sail, a subset of Hoon. This Sail is rendered as HTML
1413−when the file is served to a client. To learn about Sail, head over to
1414−the [Sail](/docs/learn/arvo/arvo-internals/sail) section of the docs.
1416−In `site/web/meet.udon` put:
1419−:- :~ navhome/'/meet'
1426−# Neo-Tokyo Urbit meetup
1428−
1430−Hi there! We meet once a week at The Chat to work on Urbit projects
1433−You can find out more about the group on the [about](about) page and
1434−follow our projects in [projects](projects).
1437−This is our landing page. Here we're using a few new bits of frontmatter:
1438−`navdpad`, `navmode` and `navpath`. `navdpad` just turns off the nav
1439−arrows. `navmode` can be set to 'navbar' to switch to a horizontal top
1440−nav instead of a left bar. `navpath` sets the path to load the nav
1443−Let's create `about.udon` and `projects.udon`. From Unix use the
1444−technique from before to create a new directory: `mkdir
1445−your-urbit/site/web/meet/; touch your-urbit/site/web/meet/about.udon`.
1446−Then put the following in `site/web/about.udon`:
1449−:- :~ navhome/'/meet'
1459−## Mission statement
1461−The existing framework cannot subdue the new human force that is increasing day
1462−by day alongside the irresistible development of technology and the
1463−dissatisfaction of its possible uses in our senseless social life.
1467−Membership is open to anyone. Just send a message to `~talsur-todres`.
1476−And `site/web/projects.udon`:
1479−:- :~ navhome/'/meet'
1495−;div(class "mini-module")
1496− ;script(src "/~/at/lib/js/urb.js");
1497− ;script(src "https://cdn.rawgit.com/seatgeek/react-infinite/0.8.0/dist/react-infinite.js");
1498− ;script(src "https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.11.2/moment-with-locales.js");
1499− ;script(src "https://cdnjs.cloudflare.com/ajax/libs/moment-timezone/0.5.1/moment-timezone.js");
1500− ;script(src "/talk/main.js");
1501− ;link(href "/talk/main.css", rel "stylesheet");
1502− ;talk(readonly "", chrono="reverse", station="comments");
1506−This page introduces a new thing: the `:talk` module. Inside of the
1507−`mini-module` div we load the scripts needed by the `;talk`
1508−component. The `;talk` component is a static component for
1509−displaying a feed from a talk channel inline. Here we're going to
1510−display the discussion from our active projects inline.
1512−We'll need a few active projects though. From unix: `mkdir
1513−your-urbit/site/web/meet/projects; touch
1514−your-urbit/site/web/meet/projects/bike.udon`.
1516−In `site/web/meet/projects/bike.udon`:
1519−:- :~ navhome/'/meet'
1523− title/'Kaneda's Bike'
1528−# Urbit on a Motorcycle
1530−Discussion on getting urbit to power Kaneda's motorcycle.
1533−Here we just use the `comments` frontmatter to enable comments on the page.
1534−Adding other imaginary projects is left to the reader.
1536−Building a static site takes only a few minutes and a few Udon files. Have fun!