Feat/entries

.cspell/custom-words.txt

@@ -2,6 +2,8 @@
 # Dev Portal content
 agent-centricity
 Anwaar
+Automerge
+automerge
 buildinputs
 builtins
 Brisebois
@@ -11,9 +13,13 @@ CRDT
 d'Aoust
 fixt
 gnused
+Hellerstein
+imdb
+IMDB
 identicon
 identicons
 IPFS
+Kleppmann
 NixOS
 nixpkgs
 pkgs

.cspell/template-words.txt

@@ -8,6 +8,7 @@ endlink
 endmacro
 endrenderlayoutblock
 gtag
+katex
 layoutblock
 MSIE
 newblock

.cspell/words-that-should-exist.txt

@@ -3,6 +3,7 @@ affordance
 affordances
 automations
 birthdate
+chrono
 counterparties
 counterparties'
 counterparty
@@ -16,6 +17,7 @@ permissioned
 permissivity
 runtimes
 sandboxed
+scaffolder
 spacebar
 todo
 todos

11ty-extensions/markdown-it-config.js

@@ -81,10 +81,7 @@ const validateDetailsBlock = (params) => {
 
 /* End Details Block code */
 
-/**
- * Configures Markdown-it lib plugins etc. Meant to be called from .eleventy.js
- * @param {*} eleventyConfig
- */
+// Set up the Markdown-it parser here.
 
 const mdLib = markdownIt();
 
@@ -107,6 +104,7 @@ mdLib.use(markdownItContainer, "intro");
 mdLib.use(markdownItContainer, "orientation");
 mdLib.use(markdownItContainer, "storystep");
 mdLib.use(markdownItContainer, "h-author");
+mdLib.use(markdownItContainer, "topic-list");
 mdLib.use(markdownItContainer, "output-block");
 
 // Admonitions

src/pages/_data/navigation/mainNav.json5

@@ -25,7 +25,12 @@
         { title: "Lifecycle Events", url: "/concepts/11_lifecycle_events/" },
       ]
     },
-    { title: "Build", url: "/build/", children: []},
+    { title: "Build", url: "/build/", children: [
+        { title: "Working with Data", url: "/build/#working-with-data", children: [
+          { title: "Entries", url: "/build/entries/" },
+        ]},
+      ]
+    },
     { title: "Resources", url: "/resources/", children: [
         { title: "HDK", url: "https://docs.rs/hdk", external: true },
         { title: "HDI", url: "https://docs.rs/hdi", external: true },

src/pages/_includes/widgets/home-tiles.njk

@@ -20,7 +20,7 @@
       {{ craneIcon() }}
       <div class="text-wrapper">
         <h2>Build Guide</h2>
-        <p>Learn how to write Holochain applications</p>
+        <p>Learn how to write and deploy Holochain applications</p>
       </div>
     {% endlinkTile %}
 

src/pages/_includes/widgets/navigation.njk

@@ -4,11 +4,11 @@
   <ul class="nav-child-level {% if isCurrentParent %}open{% endif %}">
     {% for childLink in navData %}
     <li {% if childLink.url == page.url %} aria-current="page" {% endif %}>
-      <a href="{{ childLink.url }}" {% if childLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %} >
+      <{% if childLink.url %}a href="{{ childLink.url }}" {% if childLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %}{% else %}div{% endif %} class="nav-label">
         <span>
           {{ childLink.title }}
         </span>
-      </a>
+      </{% if childLink.url %}a{% else %}div{% endif %}>
 
       {% if childLink.children %}
         {{ children(childLink.children, isCurrentParent, page) }}
@@ -29,7 +29,7 @@
       {% set isCurrentParent = topLink.url == activeParent.url %}
       <li {% if isCurrentParent %} data-is-current-parent="true" {% endif %}
         {% if topLink.url == page.url %} aria-current="page" {% endif %} >
-        <a href="{{ topLink.url }}" {% if topLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %} >
+        <a href="{{ topLink.url }}" {% if topLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %} class="nav-label">
           <span>
             {{ topLink.title }}
           </span>

src/pages/build/index.md

@@ -1,7 +1,26 @@
 ---
-title: Build on Holochain
+title: Holochain Build Guide
 ---
 
-Now that you've learned Holochain's [core concepts](/concepts/1_the_basics), [installed Holochain](/get-started/#2-installing-holochain-development-environment), and [built a basic hApp](/get-started/3-forum-app-tutorial/), it's time to deepen your Holochain knowledge to the point where you feel capable of using its full feature set to build complex applications.
+!!! note In progress
+This guide is under construction. Expect more content to be rapidly published in the first half of 2024.
+!!!
 
-The [Build Guide](/build/guide/) expands on the Core Concepts guide with code examples and a deeper level of detail on how to use various APIs and what they're doing in the background. Each page in this guide brings together all the functions and concepts you need in order to get a particular thing done.
+::: intro
+This Build Guide organizes everything you need to know about developing Holochain applications into individual topics. Each topic page stands alone as a comprehensive guide to using a given feature or implementing a given functionality. There are lots of code examples which make it clear how to do something yet are generic enough to be universally useful. These examples may not cover every single use case, though, so we'll point you to the reference documentation often.
+:::
+
+## Working with data
+
+Shared data in a Holochain application is stored as a graph database of **bases** connected by **links**. A base is identified by a 32-byte identifier such as a hash or public key, and may have data and metadata associated with it. There are four types of bases:
+
+* An **entry** is an arbitrary blob of bytes that your application code gives meaning to.
+    * An **agent ID** is a special type of entry that contains the public key of a participant in an application.
+* An **action** records the act of manipulating the graph and contains metadata about the act, such as authorship and timestamp.
+* An **external reference** is the ID of a resource that exists outside the database, such as the hash of an IPFS resource or the public key of an Ethereum address.
+
+::: topic-list
+### Topics {data-no-toc}
+
+* [Entries](/build/entries/) --- creating, reading, updating, and deleting
+:::

src/pages/concepts/2_application_architecture.md

@@ -1,6 +1,5 @@
 ---
 title: Application Architecture
-tocData: false
 ---
 
 ::: intro

src/pages/resources/glossary.md

@@ -581,7 +581,10 @@ A Holochain application design pattern, in which one [DHT](#distributed-hash-tab
 
 #### Logical monotonicity
 
-The property of a set of facts whereby the truth of prior facts are never negated by the addition of later facts. [CALM](#consistency-as-logical-monotonicity-calm-theorem) relies on functions that exhibit this property. For example, Holochain's [source chain](#source-chain) and [DHT](#distributed-hash-table-dht) only add new data without removing old data, simulating deletions and modifications ([CRUD](#create-read-update-delete-crud)) by recording actions which override the status of, but don't remove, the data they refer to.
+The property of a system whereby [monotonicity](#monotonicity) is applied to state changes. Practically this means that state changes are only accumulated, never forgotten, so that the system's final state results from the application of all accumulated state changes. [CALM](#consistency-as-logical-monotonicity-calm-theorem) systems such as Holochain are logically monotonic. Two examples of this in Holochain are:
+
+* An [agent](#agent)'s [source chain](#source-chain) is an event journal that only adds state change operations, never removes them.
+* An application's [DHT](#distributed-hash-table-dht) only adds new data without removing old data, simulating deletions and modifications ([CRUD](#create-read-update-delete-crud)) by recording actions which override the status of, but don't remove, the data they refer to.
 
 #### Membrane
 
@@ -614,6 +617,10 @@ An application architecture pattern that encourages small, single-purpose [back
 
 An extension to [countersigning](#countersigning), in which a number of optional witnesses are also involved as [counterparties](#counterparty) signing the session, a majority of which must sign in order for the session to complete. One optional witness must also be nominated as the session's [enzyme](#enzyme).
 
+#### Monotonicity
+
+A property of a function whereby values are either non-decreasing or non-increasing (that is, values may stay the same, but if they change, they may only ever go up or go down). An example in Holochain can be found in the timestamps of an [agent](#agent)'s [source chain](#source-chain), where a source chain [action](#action) can never be earlier than the action that precedes it. See also [logical monotonicity](#logical-monotonicity).
+
 #### Mutual sovereignty
 
 The relationship between the autonomy of the individual and the collective intentions of the group. A successful [commons](#commons) finds a healthy tension between these opposites. Holochain's design is based on this principle, empowering [participants](#participant) to control their own identity and responses to their peers by equipping each of them with a full copy of the application's code. This code constitutes a formal, executable definition of the group's rules and norms, as [DNA](#dna) modules, so by running the application a participant consents to become a member of the group and be bound by those rules and norms.

src/pages/resources/index.md

@@ -72,6 +72,7 @@ There are three main developer binaries, and one user-oriented binary. You can r
 
 The developer community has created some useful utilities, libraries, and reusable modules for you to use in your own apps.
 
+* [Syn](https://github.com/holochain/syn) provides back-end and front-end libraries for creating real-time collaboration apps.
 * [Holochain Open Dev](https://github.com/holochain-open-dev/) is a collection of reusable zomes and template repos from the developer community.
     * [`profiles`](https://github.com/holochain-open-dev/profiles) lets you store user profile information.
     * [`peer-status`](https://github.com/holochain-open-dev/peer-status) lets peers communicate their status (e.g., 'online', 'busy', 'on holiday') with each other.
@@ -99,4 +100,13 @@ Studying existing Holochain applications and tutorials can provide valuable insi
 While you'll learn a lot looking at the source code from the above GitHub projects, we've also produced some training material as a result of running courses in collaboration with our education partner Mythosthesia.
 
 * [Developer training materials](https://github.com/holochain-immersive) from past courses
-* [Self-paced training course](https://resources.holochain.org/self-paced-training-signup/) in video format
+* [Self-paced training course](https://resources.holochain.org/self-paced-training-signup/) in video format
+
+## Concepts useful for understanding and building distributed systems
+
+Holochain builds on a wealth of research and knowledge about distributed systems. Here are some carefully picked resources to help you on your journey:
+
+* [Keeping CALM: When Distributed Consistency is Easy](https://arxiv.org/abs/1901.01930), a paper by Joseph M Hellerstein and Peter Alvaro that lays down the mathematical foundation for distributed systems that don't need coordination protocols, such as Holochain.
+* [CRDT.tech](https://crdt.tech), a resource for learning about conflict-free replicated data types (CRDTs), data structures that let multiple users make concurrent updates to a resource with little to no manual conflict resolution.
+* [Yjs](https://yjs.dev/) and [Automerge](https://automerge.org/), two CRDTs that can operate on arbitrary JSON. Syn (mentioned above under [Libraries](#libraries)) uses Automerge.
+* [Local-first software: You own your data, in spite of the cloud](https://github.com/holochain/syn), a paper by Martin Kleppmann et al of Ink & Switch that explores the user experience of local-first software built on CRDTs.

src/scss/_navigation.scss

@@ -29,19 +29,6 @@
         transition: all .75s;
         text-decoration: none;
 
-        // Add a span so that we can use the border to indicate current page and
-        //   control the size of the indicator independent of the box size of the a tag
-        span {
-          display: inline-flex;
-          align-items: flex-end;
-          padding-left: $current-page-highlight-padding;
-          border-left: 4px solid transparent;
-
-          svg {
-            margin: 0 0 6px 6px;
-          }
-        }
-
         @include externalLinkIcon($link-color);
 
         &:hover {
@@ -50,6 +37,19 @@
         }
       }
 
+      // Add a span so that we can use the border to indicate current page and
+      //   control the size of the indicator independent of the box size of the a tag
+      .nav-label span {
+        display: inline-flex;
+        align-items: flex-end;
+        padding-left: $current-page-highlight-padding;
+        border-left: 4px solid transparent;
+
+        svg {
+          margin: 0 0 6px 6px;
+        }
+      }
+
       li {
         margin-bottom: unset;
 
@@ -100,31 +100,35 @@
           /* Because we want the whole row in which the nav link sits to be
           clickable, we can't rely on just adding a blanket margin to
           .nav-child-level. Instead, we add increasing padding to nested
-          block-display links, which means we have to do it manually for each
+          block-display wrappers, which means we have to do it manually for each
           nesting level. This imposes a limit on how many nesting levels to
           support, because we don't want to repeat the below code infinitely. */
-          a {
+          .nav-label {
             padding: 3px 0 4px 12px;
           }
 
+          div.nav-label {
+            font-style: italic;
+          }
+
           ul.nav-child-level {
-            a {
+            .nav-label {
               padding-left: 24px;
             }
 
             ul.nav-child-level {
-              a {
+              .nav-label {
                 padding-left: 36px;
               }
 
               ul.nav-child-level {
-                a {
+                .nav-label {
                   padding-left: 48px;
                 }
 
                 /* I think that's enough levels of nesting, don't you? */
                 ul.nav-child-level {
-                  a {
+                  .nav-label {
                     padding-left: 60px;
                   }
                 }

src/scss/_svg-icons.scss

@@ -74,6 +74,12 @@ $shovelIcon: url("data:image/svg+xml,%3Csvg%20viewBox%3D'0%200%201200%201200'%20
   }
 }
 
+$pageIcon: url("data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 -150 1200 1200' xmlns='http://www.w3.org/2000/svg'%3E%3Cg%3E%3Cpath d='m806.4 1042.8c86.398 0 156-69.602 156-156v-474-1.1992-4.8008-1.1992c0-2.3984-1.1992-3.6016-2.3984-6 0-1.1992 0-1.1992-1.1992-2.3984s-1.1992-2.3984-2.3984-3.6016c0-1.1992-1.1992-1.1992-1.1992-2.3984-1.1992-1.1992-1.1992-2.3984-2.3984-3.6016l-1.1992-1.1992-232.8-219.6c-1.1992-1.1992-2.3984-2.3984-4.8008-3.6016 0 0-1.1992 0-1.1992-1.1992-1.1992-1.1992-2.3984-1.1992-4.8008-2.3984-1.1992 0-1.1992 0-2.3984-1.1992-1.1992 0-3.6016-1.1992-4.8008-1.1992h-1.1992c-2.3984 0-4.8008-1.1992-6-1.1992h-300c-86.398 0-156 69.602-156 156v573.6c0 86.398 69.602 156 156 156l412.8-0.003907zm-76.797-766.8 105.6 99.602h-105.6zm-420 610.8v-573.6c0-46.801 37.199-84 84-84h264v183.6c0 20.398 15.602 36 36 36h196.8v438c0 46.801-37.199 84-84 84h-412.8c-46.801 0-84-37.199-84-84z'/%3E%3Cpath d='m423.6 676.8h198c20.398 0 36-15.602 36-36 0-20.398-15.602-36-36-36h-198c-20.398 0-36 15.602-36 36 0 20.398 16.797 36 36 36z'/%3E%3Cpath d='m423.6 846h354c20.398 0 36-15.602 36-36s-15.602-36-36-36h-354c-20.398 0-36 15.602-36 36s16.797 36 36 36z'/%3E%3C/g%3E%3C/svg%3E");
+
+@mixin addPageIcon() {
+  @include addInlineIcon(before, $pageIcon);
+}
+
 @mixin externalLinkIcon($color) {
   $color-encoded: encodecolor($color);
   &:not(.no-away), :not(.no-away) &, .no-away &.away {
@@ -82,4 +88,3 @@ $shovelIcon: url("data:image/svg+xml,%3Csvg%20viewBox%3D'0%200%201200%201200'%20
     }
   }
 }
-

src/scss/_widgets.scss

@@ -344,6 +344,29 @@ a.link-tile {
   }
 }
 
+/* A special styling for lists of links to sub-pages. Used in the build guide. */
+.topic-list {
+  padding: 1em;
+  background-color: #f7f7f7;
+
+  /* Unless otherwise specified with `class="not-topic-page"`, links in a topic
+  list are assumed to point to topic pages. */
+  a:not(.not-topic-page, .header-anchor) {
+    font-weight: bold;
+    @include addPageIcon;
+  }
+
+  > :first-child {
+    margin-top: 0;
+  }
+
+  > :last-child {
+    margin-bottom: 0;
+  }
+}
+
+/* Enlarged text with a rule on the left side, meant to call out an interesting
+   paragran at the top of a page. */
 .intro {
   font-size: $fs-even-bigger;
   border-left: 4px solid $cl-gray;
@@ -367,7 +390,6 @@ a.link-tile {
 }
 
 .storystep {
-
   /* Horizontal rules can be used to break up content in a story step.
   Make them nice and light. */
   hr {