Merge pull request #438 from holochain/chore/rename-coreconcepts-elem…

…ents

Remove 'coreconcepts-' prefix from styles, admonition blocks, etc

.cspell/template-words.txt

@@ -15,5 +15,5 @@ pagefind
 rocketship
 renderlayoutblock
 srcset
-storysequence
+storystep
 surpress

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

@@ -87,9 +87,9 @@ export default function(eleventyConfig) {
     //Configure markdown-it plugins
     mdLib.use(markdownItAttrs);
     mdLib.use(markdownItAnchor, { tabIndex: false, slugify: s => slugify(s) });
-    mdLib.use(markdownItContainer, "coreconcepts-intro");
-    mdLib.use(markdownItContainer, "coreconcepts-orientation");
-    mdLib.use(markdownItContainer, "coreconcepts-storysequence");
+    mdLib.use(markdownItContainer, "intro");
+    mdLib.use(markdownItContainer, "orientation");
+    mdLib.use(markdownItContainer, "storystep");
     mdLib.use(markdownItContainer, "h-author");
     mdLib.use(markdownItContainer, "output-block");
 

11ty-markdown-changes.md

@@ -11,9 +11,9 @@
 
 ## Divs
   - No more `markdown=1`, instead leave a blank line after.
-  - coreconcepts-intro, coreconcepts-orientation, and coreconcepts-storysequence divs have been created as MD containers. Use:
+  - Core Concepts intro and orientation divs have had their `coreconcepts-` prefixes removed and can now be created as MD containers. `coreconcepts-storysequence` blocks have been replaced with individual `storystep` blocks around each step in a story sequence. Use:
     ```
-    ::: coreconcepts-intro
+    ::: intro
     words words
     :::
     ```

README.md

@@ -72,26 +72,26 @@ Additionally the following `markdown-it` plugins have been added:
   There are of course more details. See the docs at [markdown-it-attrs](https://github.com/arve0/markdown-it-attrs) for more.
 - [markdown-it-container](https://github.com/markdown-it/markdown-it-container) Plugin for creating block-level custom containers. For example:
   ```
-  ::: coreconcepts-intro
+  ::: intro
   Blah blah
   :::
   ```
 
   renders as
 
   ```
-  <div class="coreconcepts-intro">
+  <div class="intro">
     <p>Blah blah</p>
   </div>
   ```
   Please note: The closing `:::` is required. Also if you need to nest containers then the outer container gets an additional `:`.
   Each container type needs to be configured in `markdown-it-config.js` for examples and to add more. This one provides a lot of flexibility.
 
 ## Site search and indexing
-The site uses the [Pagefind](https://pagefind.app/) library to index the contents of the site and to find search results upon request. 
-The documentation is quite good. One thing to note; pages are indexed based on the inclusion of the `data-pagefind-body` 
-attribute on a page. It is included on all of the main pages (all but the Design System). If you need to remove some or all of a page 
-from indexing you can use the `data-pagefind-ignore` attribute. See (https://pagefind.app/docs/indexing/) for details. 
+The site uses the [Pagefind](https://pagefind.app/) library to index the contents of the site and to find search results upon request.
+The documentation is quite good. One thing to note; pages are indexed based on the inclusion of the `data-pagefind-body`
+attribute on a page. It is included on all of the main pages (all but the Design System). If you need to remove some or all of a page
+from indexing you can use the `data-pagefind-ignore` attribute. See (https://pagefind.app/docs/indexing/) for details.
 
 ## Setup for Dev
 - `npm install`

src/custom/style.css

@@ -149,21 +149,21 @@ article img { display: table; margin-left: auto; margin-right: auto; }
 
 /* Core Concepts */
 
-.md-typeset .coreconcepts-intro { font-size: .98rem; border-left: .2rem solid rgba(0,0,0,.2); padding-left: 0.6rem; font-weight: 500; line-height: 1.55; }
-.md-typeset .coreconcepts-intro p { letter-spacing: -.3px; }
-.md-typeset .coreconcepts-orientation { margin: 2.2rem 0; padding: 1.6rem 1.2rem 1.8rem; background: #F8F8F8; position: relative; }
-.md-typeset .coreconcepts-orientation :first-child { margin-top: 0; }
-.md-typeset .coreconcepts-orientation :last-child { margin-bottom: 0; }
-.md-typeset .coreconcepts-orientation h2, .md-typeset .coreconcepts-orientation h3 { position: relative; }
-.md-typeset .coreconcepts-orientation a { font-weight: 500; letter-spacing: -.3px; }
-.md-typeset .coreconcepts-orientation i { position: absolute; left: -40px; top: 13px; font-size: 28px; color: #3915ad; }
-.md-typeset .coreconcepts-orientation ol { margin-bottom: -12px; margin-left: 0; }
-.md-typeset .coreconcepts-storysequence > ol { margin-left: 0; }
-.md-typeset .coreconcepts-storysequence > ol > li { list-style: none; padding: 0.6rem; background: #F8F8F8; margin: 1rem 0; }
-.md-typeset .coreconcepts-storysequence > ol > li > img { margin-bottom: 1rem; }
+.md-typeset .intro { font-size: .98rem; border-left: .2rem solid rgba(0,0,0,.2); padding-left: 0.6rem; font-weight: 500; line-height: 1.55; }
+.md-typeset .intro p { letter-spacing: -.3px; }
+.md-typeset .orientation { margin: 2.2rem 0; padding: 1.6rem 1.2rem 1.8rem; background: #F8F8F8; position: relative; }
+.md-typeset .orientation :first-child { margin-top: 0; }
+.md-typeset .orientation :last-child { margin-bottom: 0; }
+.md-typeset .orientation h2, .md-typeset .orientation h3 { position: relative; }
+.md-typeset .orientation a { font-weight: 500; letter-spacing: -.3px; }
+.md-typeset .orientation i { position: absolute; left: -40px; top: 13px; font-size: 28px; color: #3915ad; }
+.md-typeset .orientation ol { margin-bottom: -12px; margin-left: 0; }
+.md-typeset .storysequence > ol { margin-left: 0; }
+.md-typeset .storysequence > ol > li { list-style: none; padding: 0.6rem; background: #F8F8F8; margin: 1rem 0; }
+.md-typeset .storysequence > ol > li > img { margin-bottom: 1rem; }
 
 @media (max-width: 1600px) {
-	.md-typeset .coreconcepts-orientation i { left: -36px; top: 12px; font-size: 26px; }
+	.md-typeset .orientation i { left: -36px; top: 12px; font-size: 26px; }
 }
 
 /* Tables */

src/pages/build/guide/index.md

@@ -2,7 +2,7 @@
 title: Holochain Build Guide
 ---
 
-::: coreconcepts-intro
+::: 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.
 :::
 

src/pages/concepts/10_countersigning.md

@@ -2,11 +2,11 @@
 title: "Countersigning: Reaching Agreement Between Peers"
 ---
 
-::: coreconcepts-intro
+::: intro
 Although there's no global consensus in a Holochain application, it's sometimes useful for two or more parties to record shared agreements. Countersigning allows them to coordinate the writing of a single entry across all their source chains.
 :::
 
-::: coreconcepts-orientation
+::: orientation
 ### What you'll learn
 
 1. [Differences between Holochain, client/server, and blockchain](#agreement-versus-consensus)
@@ -45,64 +45,109 @@ In order to safely coordinate the writing of a single new action to both of thei
 
 Here's a more in-depth look at this process. Keep in mind that it's meant to be an automated process, finished within a few seconds while Alice and Bob are both online. Any human agreement (such as negotiating meeting times, contract terms, or transaction amount) should happen beforehand.
 
-::: coreconcepts-storysequence
-
+::: storystep
 ![](/assets/img/concepts/10.2-entry-exchange.png){.sz80p} {.center}
 
+---
+
 Alice and Bob exchange the details needed to create the entry that will be countersigned.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.3-preflight.png){.sz80p} {.center}
 
+---
+
 Alice creates a **preflight request** containing:
 
 * The parties involved (her and Bob in this case)
 * The hash of the entry that will be countersigned
 * The time window in which the countersigning must complete
 * A stub of the action to go along with the entry, which contains its action type and entry type (currently create-entry and update-entry actions can be countersigned; in the future delete-entry, create-link, and delete-link actions will be too)
 * Optional arbitrary application data
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.4-preflight-send.png){.sz80p} {.center}
 
+---
+
 Alice sends the preflight request to Bob for approval. (You can implement this any way you like, but a [remote call](../8_calls_capabilities/) is probably the best.) At this stage, it's expected that Bob is able to independently construct the data that will go into the countersigned entry, based perhaps on his history with Alice or the optional application data, to determine whether the request is something he wants to accept. Acceptance could be automated, or it could request Bob's intervention via a signal to his UI.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.5-preflight-inspection.png){.sz80p} {.center}
 
+---
+
 Bob's conductor attempts to accept the preflight request, which involves checking whether it is possible to write a countersigned record (that is, there are no incomplete countersigning sessions or pending source chain writes, and Alice's specified time window doesn't conflict with Bob's system clock). If everything looks good, Bob's conductor locks his source chain.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.6-bob-lock.png){.sz80p} {.center}
 
+---
+
 Bob's conductor produces a **preflight response**, containing his signature on the request and the record ID at which his source chain is currently locked. Bob sends this preflight response back to Alice.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.7-alice-lock.png){.sz80p} {.center}
 
+---
+
 Alice receives Bob's preflight response, then tries to generate a preflight response herself from the request she created. Now her own source chain is locked as well.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.8-countersigning-session.png){.sz80p} {.center}
 
+---
+
 Alice compiles both the preflight responses into a **countersigning session** structure, containing the original agreed-upon preflight request and all the responses. She shares it with Bob (again, this could be done with a remote call).
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.9-trial-commit.png){.sz80p} {.center}
 
+---
+
 Alice and Bob both create the entry to be countersigned on their own machines, which contains both the countersigning session data structure and the app data they'd previously agreed on. Then they do a trial run of committing the entry.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.10-validate.png){.sz80p} {.center}
 
+---
+
 At this point Alice and Bob's conductors take over completely from the cells. As with any commit, they attempt to validate the new action. But with a countersigned action, each participant's conductor validates it multiple times --- once from their own perspective, and once from the perspective of all the other parties. This is possible because Alice and Bob both have the same countersigning session data structure, which contains the current states of both of their source chains. If this step didn't happen, DHT validating authorities would [warrant](../7_validation/#invalid-entry) all parties for neglect, not just the one for whom the action was invalid.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.11-authorities-collect.png){.sz80p} {.center}
 
+---
+
 Once validation is finished, Alice and Bob both do a trial run of publishing the operations generated by the new action to the DHT --- but only the [store entry operations](../4_dht/#a-cloud-of-witnesses). The authorities collect the data but don't integrate it into their DHT stores; right now they're simply acting as witnesses who wait until they've seen the operations from both Alice and Bob.
+:::
 
+::: storystep
 ![](/assets/img/concepts/10.12-authorities-distribute.png){.sz80p} {.center}
 
+---
+
 Once the authorities have collected all the data, they send the full set of actions back to both of them.
+:::
 
 !!! info Timeouts
 If Alice and Bob reach the end of the time window without receiving this action set, their conductors discard the new action and unlock their source chains as if nothing had happened. Likewise, the authorities discard the pre-published data if they don't collect all the required signatures within the time window. There is no built-in feature to retry an expired session, but it could be built into the application.
 !!!
 
+::: storystep
 ![](/assets/img/concepts/10.13-commit-and-publish.png){.sz80p} {.center}
 
+---
+
 When Alice and Bob's conductors each receive the full set of actions, they finally unlock their source chains, commit the actions, and publish _all_ the resulting operations to the DHT as normal. This creates a permanent, public record of all parts of the transaction.
 :::
 

src/pages/concepts/11_lifecycle_events.md

@@ -2,11 +2,11 @@
 title: "Lifecycle events: reacting to external triggers"
 ---
 
-::: coreconcepts-intro
+::: intro
 In the course of its existence, the conductor triggers **lifecycle events**, to which a cell can respond with specially named callbacks.
 :::
 
-::: coreconcepts-orientation
+::: orientation
 ### What you'll learn
 
 * [How to tell the conductor about the entry types your zome defines](#entry-type-definition-callbacks)

src/pages/concepts/1_the_basics.md

@@ -2,11 +2,11 @@
 title: "Holochain Core Concepts: What is Holochain?"
 ---
 
-::: coreconcepts-intro
+::: intro
 Holochain is an open-source application development framework and peer-to-peer networking protocol. It allows you to create **actually serverless applications** with high levels of **security, reliability, and performance**. Every participant runs the application on their own device, creates and stores their own data, and talks directly to other participants. The security of the application is supported by both cryptography and peer accountability.
 :::
 
-::: coreconcepts-orientation
+::: orientation
 ### <i class="fas fa-thunderstorm"></i> What you'll learn
 
 1. [The problem with centralized architectures](#the-problem-with-centralized-architectures)

src/pages/concepts/2_application_architecture.md

@@ -2,10 +2,10 @@
 title: Application Architecture
 ---
 
-::: coreconcepts-intro
+::: intro
 Applications built with Holochain are highly **modular**. This makes it easy to share code and [compose](https://en.wikipedia.org/wiki/Composability) smaller pieces together into larger wholes. Each functional part of a Holochain application, called a **DNA**, has its own application logic, isolated peer-to-peer network, and shared database.
 
-::: coreconcepts-orientation
+::: orientation
 ### <i class="fas fa-thunderstorm"></i> What you'll learn
 
 1. [Agent-centricity](#agent-centricity)

src/pages/concepts/3_source_chain.md

@@ -2,11 +2,11 @@
 title: "The Source Chain: A Personal Data Journal"
 ---
 
-::: coreconcepts-intro
+::: intro
 Each participant in a Holochain network creates and stores their own data in a journal called a **source chain**. Each journal entry is cryptographically signed by its author and is immutable once written.
 :::
 
-::: coreconcepts-orientation
+::: orientation
 ### <i class="fas fa-thunderstorm"></i> What you'll learn
 
 1. [How agent identities are created](#agent-identity)

src/pages/concepts/4_dht.md

@@ -2,11 +2,11 @@
 title: "The DHT: A Shared, Distributed Graph Database"
 ---
 
-::: coreconcepts-intro
+::: intro
 Agents share records of their actions, including any data meant to be shared with the group, in a [**distributed hash table (DHT)**](https://en.wikipedia.org/wiki/Distributed_hash_table). This database provides redundancy and availability for data and gives the network the power to detect and take action against corruption.
 :::
 
-::: coreconcepts-orientation
+::: orientation
 ### <i class="fas fa-thunderstorm"></i> What you'll learn
 
 1. [The downsides and risks of self-owned data](#self-owned-data-isn-t-enough)
@@ -65,32 +65,52 @@ Every peer knows about all of its closest neighbors and a few faraway acquaintan
 
 Let's see how this works with a very small address space. Instead of public keys and hashes, we're just going to use letters of the alphabet, where the first letter of a word is its address.
 
-::: coreconcepts-storysequence
-
+::: storystep
 ![](/assets/img/concepts/4.5-alice-neighborhood.png){.sz80p} {.center}
 
+---
+
 Alice lives at address A. Her neighbors to the left are Diana and Fred, and her neighbors to the right are Zoë and Walter.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.7-alice-publish-address-calculation.png){.sz80p} {.center}
 
+---
+
 Alice creates an entry containing the word "molecule", whose address is M.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.8-authority-resolution.png){.sz80p} {.center}
 
+---
+
 Of all of Alice's neighbors, Fred is closest to that address, so she asks him to store it. Fred hasn't claimed authority for that address, so he tells Alice about his neighbor Louise.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.9-gossip-publish.png){.sz80p} {.center}
 
+---
+
 Alice shares the entry with Louise, who agrees to store it because her neighborhood covers M.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.10-gossip-resilience.png){.sz80p} {.center}
 
+---
+
 Louise shares it with her neighbor, Norman, in case she goes offline.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.11-retrieval.png){.sz80p} {.center}
 
-Rosie is a word collector who learns that an interesting new word lives at address is M. She asks her neighbor, Norman, if he has it. Louise has already given him a copy, so he delivers it to Rosie.
+---
 
+Rosie is a word collector who learns that an interesting new word lives at address is M. She asks her neighbor, Norman, if he has it. Louise has already given him a copy, so he delivers it to Rosie.
 :::
 
 ## Resilience and availability
@@ -103,24 +123,36 @@ Using information about their neighbors' uptime, cooperating agents work hard to
 
 Let's see how this plays out in the real world.
 
-::: coreconcepts-storysequence
-
+::: storystep
 ![](/assets/img/concepts/4.12-healthy-network.png){.sz80p} {.center}
 
+---
+
 An island is connected to the mainland by a radio link. They communicate with each other using a Holochain app.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.13-partition.png){.sz80p} {.center}
 
+---
+
 A hurricane blows through and wipes out both radio towers. The islanders can't talk to the mainlanders, and vice versa, so some DHT neighbors are unreachable. But everyone can still talk to their physical neighbors. None of the data is lost, but not all of it is available to each side.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.14-resilience-building.png){.sz80p} {.center}
 
+---
+
 On both sides, all agents attempt to improve resilience by enlarging their arcs. Meanwhile, they operate as usual, talking with one another and creating new data.
+:::
 
+::: storystep
 ![](/assets/img/concepts/4.15-partition-healing.png){.sz80p} {.center}
 
-The radio towers are rebuilt, the network partition heals, and new data syncs up across the DHT. At this point everyone has the option of shrinking their arc sizes and prune overly redundant data (although experience has shown them that it might be best to overcompensate in case another hurricane comes around).
+---
 
+The radio towers are rebuilt, the network partition heals, and new data syncs up across the DHT. At this point everyone has the option of shrinking their arc sizes and prune overly redundant data (although experience has shown them that it might be best to overcompensate in case another hurricane comes around).
 :::
 
 ## A cloud of witnesses