@@ -8,81 +8,54 @@ Sail is Hoon markup that’s used to render a web page with XML. But what makes
88
99Udon 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.
1010
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.
1212
1313## Table of Contents
1414
15+- [Getting Started](#getting-started)
16+
1517- [Sail: A Guide](#sail)
1618
1719- [Udon: A Guide](#udon)
1820
19−- [Udon: A Simple Blog](#blog)
20−
21−- [Udon: A Static Site](#static)
22−
23−## Getting Started
21+## Getting Started {#getting-started}
2422
2523Before 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)
2725
28−To host that output, your ship also has a web-server, called
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
26+To host that output, your ship also has a web-server that can be found at
27+`localhost` (default port 80) if it’s your first ship that’s running on the
3128machine, `http://localhost:8081/` if it’s the second ship on that same machine,
3229and so on. In the startup messages, a ship will tell you which HTTP port it's
3330using.
3431
35−The `/web` directory of the `%home` desk is served by default. You can change
36−which desk you're serving by using the command `|serve` in the Dojo. If you
37−have already created and mounted a desk named `%sandbox`, for example, you can
38−switch to serving it with this command:
39−
40−```
41−|serve %sandbox
42−```
32+Udon and Sail files are often run as independent files (`.udon` and `.hoon`
33+respectively), but for the purpose of this guide, we will run them out of the
34+`frontpage.hoon` file located in the `/gen` directory. The default content of
35+`frontpage.hoon` is Sail code.
4336
44−The first time you serve a desk, `/web` will be included as default. After that,
45−you will need to explicitly append `/web` to the desk you're switching to --
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.
49−
50−To switch back to your `%home` desk and set `/web` as your root directory, run:
37+To use `frontpage.hoon`, we use a `|serve` command like this one in your ship's
38+Dojo:
5139
5240```
53−|serve %/web
41+|serve /test %home /gen/frontpage/hoon
5442```
5543
56−We'll be serving the `%home` desk for the examples in this tutorial.
57−
58−### Rendering
44+This command has three arguments:
45+- The first is the URL we want to bind our site to. We chose `/test`, so the URL
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
48+this tutorial.
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`.
5951
60−That server has access to source files located in `/<your-urbit>/home/web` and
61−any sub-folders thereof. For the purposes of this tutorial, we will only be
62−using files that are located in the `/<your-urbit>/home/web/pages` path.
52+Run the command `|serve /test %home /gen/frontpage/hoon`. Now navigate to
53+`localhost/test` (or `localhost:8081/test` if your ship is on that port) in your
54+browser, and you should see the rendered Sail.
6355
64−There is an important distinction between these two paths. According to
65−`/ren/urb.hoon`, any file inside of `/web` or any of its sub-directories
66−is put through a tree of renderers specified at `/ren/urb/tree.hoon`
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.
72−
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.
78−
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.
82−
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/`.
56+**Note:** Important to remember that every time you edit a file in your ship's
57+pier (Unix directory), including `frontpage.hoon`, you need to run `|commit %home`
58+to copy those changes to Urbit.
8659
8760## <a name="sail"></a>Sail: A Guide
8861
@@ -122,14 +95,13 @@ It’s easy to see how Sail can directly translate to HTML:
12295</html>
12396```
12497
125−Save the above Sail code in `/home/web/pages/firstsail.hoon`, and the above
126−HTML code in `/home/web/pages/firsth.html`. Access the resulting pages by
127−navigating to `http://localhost:8080/pages/firstsail` and
128−`http://localhost:8080/pages/firsth.html`, respectively, in your browser. The
129−resulting pages should be identical!
98+You can test above Sail code by placing it
99+under `^- manx` in your `frontpage.hoon` file, and then running `|commit %home`
100+in the Dojo. If you've already run the `|serve` command code from the first
101+section, the new content should appear at `localhost/test`.
130102
131−It shouldn't be hard to see the similarities here. So let's go into more
132−detail about what the differences are.
103+It shouldn't be hard to see the similarities between Sail and HTML. So let's go
104+into more detail about what the differences are.
133105
134106### Tags and Closing
135107
@@ -701,25 +673,30 @@ allowing it to be used as standalone prose in its own file or embedded inside a
701673Hoon source file, in which case it will be parsed into a tree of HTML nodes
702674using Hoon's XML-templating syntax, Sail.
703675
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.
708−
709676There are quite a few similarities between Udon and the
710677CommonMark standard, but there are enough differences that you shouldn't rely on
711678existing knowledge of the latter. Udon generally supports only one
712679syntax for each type of HTML node it emits. Udon is also stricter than
713680Markdown: some syntax errors will prevent the file from being parsed at all.
714681
715−We provide a few simple examples [here](#examples) of how to publish
716−Udon files using our web interface.
682+## Testing Udon
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.
686+
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`.
717691
718692## Udon Syntax
719693
720694### Front Matter
721695
722−The first thing on your file is a chunk of code called the front matter. It
696+> Note: The Front Matter section only applies to .udon files, and not the
697+frontpage.hoon testing method.
698+
699+The first thing on a `.udon` file is a chunk of code called the front matter. It
723700contains metadata about your page, such as date, title, and position relative
724701to sibling pages.
725702
@@ -1255,282 +1232,3 @@ Produces:
12551232 <br>
12561233 <small>[reactive publishing intensifies]</small>
12571234</p>
1258−
1259−
1260−## <a name="blog"></a>A Simple Udon Blog
1261−
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.
1263−
1264−First, let's setup a desk to serve our posts from:
1265−
1266−```
1267−|merge %site ~your-urbit %home
1268−```
1269−
1270−Then let's mount that desk to unix:
1271−
1272−```
1273−|mount /=site=
1274−```
1275−
1276−You should now be able to find a `/site` folder inside of your pier
1277−directory (either `comet/` or `your-urbit/`).
1278−
1279−To begin serving files from this new desk use `|serve`:
1280−
1281−```
1282−|serve %site
1283−```
1284−
1285−First let's create the landing page for our blog. Create the file
1286−`site/web/blog.udon`:
1287−
1288−```
1289−:- :~ anchor/'none'
1290− ==
1291−;>
1292−
1293−# Hello
1294−
1295−This is a simple blog I built on Urbit.
1296−
1297−;list(dataType "post");
1298−```
1299−
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
1302−started your urbit.
1303−
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.
1308−
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:
1315−
1316−```
1317−:- :~ navhome/'/blog'
1318− type/'post'
1319− date/'~2016.6.20'
1320− title/'My first post!'
1321− ==
1322−;>
1323−
1324−Is this a decentralized Medium? Let's find out.
1325−
1326−But first, how about a long quote from Paramenides:
1327−
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.
1337−
1338−Good to get that out of the way.
1339−```
1340−
1341−You should be able to view this file at:
1342−`http://localhost:8080/blog/post-1.udon`.
1343−
1344−You'll also notice that
1345−now the list of posts here: `http://localhost:8080/blog` has
1346−updated.
1347−
1348−Here we use two pieces of front-matter worth noting: `type` and `navhome`.
1349−
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.
1353−
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`
1356−
1357−Adding posts is as easy as dropping Udon files into the `blog/`
1358−directory. Pretty easy!
1359−
1360−### Blog comments
1361−
1362−Now let's enable comments on a blog post.
1363−
1364−First, turn comments on by editing the frontmatter in `post-1.udon`. Your
1365−frontmatter should look like this:
1366−
1367−```
1368−:- :~ navhome/'/blog'
1369− type/'post'
1370− date/'~2018.6.20'
1371− title/'Blog comments'
1372− comments/'true'
1373− ==
1374−;>
1375−```
1376−
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.
1379−
1380−Try posting a comment! When you do you should see the following in
1381−your console:
1382−
1383−```
1384−+ /~your-urbit/home/55/web/blog/post-1/comments/~2016.6.20..23.20.54..0b88/md
1385−------------[0]
1386−~your-urbit[tree]: receiving comments, ;join %comments for details
1387−```
1388−
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.
1392−
1393−Use `;join` to keep up with comments as they get posted:
1394−
1395−```
1396−;join ~your-urbit/comments
1397−```
1398−
1399−That's it! Easy.
1400−
1401−## <a name="static"></a>A Static Site
1402−
1403−Hosting a static tree of content is easy. Let's put together a really
1404−simple site for an imaginary Urbit meetup group.
1405−
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
1408−unix.
1409−
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.
1415−
1416−In `site/web/meet.udon` put:
1417−
1418−```
1419−:- :~ navhome/'/meet'
1420− navdpad/'false'
1421− navpath/'/meet'
1422− navmode/'navbar'
1423− ==
1424−;>
1425−
1426−# Neo-Tokyo Urbit meetup
1427−
1428−
1429−
1430−Hi there! We meet once a week at The Chat to work on Urbit projects
1431−together.
1432−
1433−You can find out more about the group on the [about](about) page and
1434−follow our projects in [projects](projects).
1435−```
1436−
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
1441−items from.
1442−
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`:
1447−
1448−```
1449−:- :~ navhome/'/meet'
1450− navdpad/'false'
1451− navpath/'/meet'
1452− navmode/'navbar'
1453− title/'About'
1454− ==
1455−;>
1456−
1457−# About
1458−
1459−## Mission statement
1460−
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.
1464−
1465−## Members
1466−
1467−Membership is open to anyone. Just send a message to `~talsur-todres`.
1468−
1469−- Shōtarō Kaneda
1470−- Motoko Kusanagi
1471−- Ishikawa
1472−- Faye Valentine
1473−- Spike Spiegel
1474−```
1475−
1476−And `site/web/projects.udon`:
1477−
1478−```
1479−:- :~ navhome/'/meet'
1480− navdpad/'false'
1481− navpath/'/meet'
1482− navmode/'navbar'
1483− title/'Projects'
1484− ==
1485−;>
1486−
1487−# Projects
1488−
1489−## Active
1490−
1491−;list;
1492−
1493−## Discussion
1494−
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");
1503−==
1504−```
1505−
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.
1511−
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`.
1515−
1516−In `site/web/meet/projects/bike.udon`:
1517−
1518−```
1519−:- :~ navhome/'/meet'
1520− navdpad/'false'
1521− navpath/'/meet'
1522− navmode/'navbar'
1523− title/'Kaneda's Bike'
1524− comments/'true'
1525− ==
1526−;>
1527−
1528−# Urbit on a Motorcycle
1529−
1530−Discussion on getting urbit to power Kaneda's motorcycle.
1531−```
1532−
1533−Here we just use the `comments` frontmatter to enable comments on the page.
1534−Adding other imaginary projects is left to the reader.
1535−
1536−Building a static site takes only a few minutes and a few Udon files. Have fun!