holochain/docs-pages

The hosted static files for the Holochain developer documentation

Docs

This repo builds the documentation for developer.holochain.org generated by 11ty (https://www.11ty.dev/).

A note about browsers

Other than a warning to the user (see unsupported-brower-warning.njk if you care) no effort has been made to accommodate non-Evergreen browsers, which is mostly to say Internet Explorer of any version. There isn't a lot of js in the rendered site, but what there is won't work, and newer CSS features are used as well.

What the heck is 11ty (an extremely quick intro)

11ty, or Eleventy, is a NodeJS based static website generator. It supports a bunch of template types, including markdown and nunjucks (https://mozilla.github.io/nunjucks/) which we use here. By default any template file in the input directory will generate an html file in the generated site. It also supports includes and data generated content. It is extremely configurable and as such the docs (https://www.11ty.dev/docs/) can be a handful, but they are quite good and are worth a look.

How are we using 11ty

The 11ty config (.eleventy.js) is the final source of truth, but the basic setup is:

• The output goes to _site.
• Template files in /src/pages are transformed into html pages in the resulting site.
• Page templates can have embedded data called Front Matter in YAML format.
• /src/pages/_includes contains overall page layouts and helpers that can be called from the page template files
• /src/pages/_data contains files that provide data that can be consumed by the templates. See Datafiles for details Uses:
  • Header Navigation
  • Contributors display
  • Community quotes display
  • Roadmap data
• assets and client-side are static assets that get copied to _site, via calls to 11ty's .addPassthroughCopy.
• copy-to-root (Not in place yet): sitemap.xml, robots.txt and _redirects (a Netlify config file with HTTP redirect commands). Copied to _site by 11ty's addPassthroughCopy.
• Also see Using Markdown Here below.

Other artifacts

• SCSS is compiled by sass via package.json script
• /src/client-side is Typescript code that is compiled by via package.json script. When building for production it is also bundled into a single script for broader browser support.

Syntax highlighting

Syntax highlighting is applied server-side during the build process. The most popular highlighting tool for 11ty is syntaxhighlight, which uses Prism.js for formatting. We don't use this plugin. Instead, we use a custom transform based on highlight.js.

There are two reasons for this:

1. highlight.js supports a lot more languages both natively and through extensions, including Svelte, which is used heavily in the Get Started guide.
2. highlight.js also supports nested languages such as JavaScript and CSS inside HTML in a Svelte template.

Here is a list of all supported languages. Use a value from the 'Aliases' column as a tag on your GitHub-style code fence, like so:

```svelte
<main>
  {#if loading}
    <div>Loading...</div>
  {:else}
    <h1>Hello world!</h1>
    <p>The weather today will be {weather}.</p>
  {/if}
</main>
```

The tag will be added to the <code> element as a language-<tag> CSS class, along with a hljs tag. The surrounding <pre> element will also get a hljs-container class. We're using the atom-one-light theme that ships with highlight.js.

Using Markdown Here

We are using a mixture of markdown and nunjucks as the main page templates. For documentation pages (as opposed to more blingy pages like the home page) md is preferred.

By default 11ty uses the markdown-it parser and we stuck with that. Additionally the following markdown-it plugins have been added:

• markdown-it-attrs allows, in particular, attributes and classes to be added. For example:

  [Holochain Launcher](https://github.com/holochain/launcher){#my-link target=_blank .a-super-cool-link}
  

  renders as

  <a href="https://github.com/holochain/launcher" id="my-link" target="_blank" class="a-super-cool-link">Holochain Launcher</a>
  

  There are of course more details. See the docs at markdown-it-attrs for more.

• markdown-it-container Plugin for creating block-level custom containers. For example:

  ::: intro
  Blah blah
  :::
  

  renders as

  <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 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
• npm run dev
• open browser to http://localhost:8080/

NPM Scripts of note

• dev: Runs 11ty & SCSS compile with browser reload.
• build: The Production build. Mostly used by CI/CD.
  • Cleans _site dir
  • Builds, autoprefixes and minifies the SCSS
  • Bundles the JS modules
    • Builds the Typescript to JS
    • Minifies the JS with Terser
    • Saves the module to _site/scripts/ dir
  • Builds 11ty with links to the bundled JS and minified CSS
• clean: Cleans out the _site dir
• build:search-index: builds the index files for the search function. This is called as pat of the build process, but if you want the search to work during local dev then you need to run this once, or you can just run build before you start the dev script.
• update-browserlist: Updates the browserlist that autoprefixer uses determine what vendor prefixes are needed for your specified browser set. Run once in a while.

docs-pages's Issues

Suggesting Edit: CRUD Operations

Page URL: http://developer.holochain.org/docs/concepts/6_modifying_and_deleting_data/

Hi! The fourth heading, "simulating immutability", should be "simulating mutability".

Suggesting Edit: Install Holochain

Page URL: http://developer.holochain.org/docs/install/

First instruction: curl https://nixos.org/nix/install
should really be: curl https://nixos.org/nix/install | sh

as per the NixOS website.

Review Holochain website and Holochain FAQ - update any outdated info

From Jimmy. He is doing a review on Holochain.
"hmmm, any intention of updating the website? The JavaScript/Lisp section doesn't really apply anymore"

Suggesting Edit: Hello Test Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_test/

Remove the following section:

orchestrator.registerScenario("description of example test", async (s, t) => { const {alice, bob} = await s.players({alice: conductorConfig, bob: conductorConfig}) // Make a call to a Zome function // indicating the function, and passing it an input const addr = await alice.call("myInstanceName", "my_zome", "create_my_entry", {"entry" : {"content":"sample content"}}) // Wait for all network activity to await s.consistency() const result = await alice.call("myInstanceName", "my_zome", "get_my_entry", {"address": addr.Ok}) // check for equality of the actual and expected results t.deepEqual(result, { Ok: { App: [ 'my_entry', '{"content":"sample content"}' ] } }) })

This section mismatches what I've arrived to so far!

My code says this:
orchestrator.registerScenario('Test hello holo', async (s, t) => { const {alice, bob} = await s.players({alice: config, bob: config}, true); const result = await alice.call('cc_tuts', 'hello', 'hello_holo', {}); t.ok(result.Ok); t.deepEqual(result, { Ok: 'Hello Holo' })

Suggesting Edit: Hello Holo Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_holo/

There is an issue compiling with 'hc package' in the 'Generate a Zome' section.
The config.toml file errors.
I found it works when I update the dependencies like this:

[dependencies]
serde = "=1.0.89"
serde_json = { version = "=1.0.39", features = ["preserve_order"] }
serde_derive = "=1.0.89"
hdk = { git = "https://github.com/holochain/holochain-rust", tag = "v0.0.34-alpha1" }
holochain_wasm_utils = { git = "https://github.com/holochain/holochain-rust", tag = "v0.0.34-alpha1" }
holochain_json_derive = "=0.0.17"

Suggesting Edit: Core Concepts

Page URL: https://developer.holochain.org/docs/concepts/5_linking_data_together/

• "ukulele" is spelled incorrectly (or differently from the content) on the illustrations

Page URL: https://developer.holochain.org/docs/concepts/3_private_data/

• There is some writing here that is visible, which reads "[ diagram: maybe this following table could be made more visual? ] [color=#f60]" above the table.

Suggesting Edit: Hello Gui Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_gui/

In the section Run a simple server, the command

python -m SimpleHTTPServer

is not valid anymore (it will cause the error 'No module named SimpleHTTPServer').

This command should be replaced by:

python -m http.server

add a link to a feedback form for the site

maybe to the github repo too, in case anyone wants to submit PRs

Suggesting Edit: Hello Holo Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_holo/

Each "run in nix-shell" prompt is really "nix-shell https://holochain.love" (or remind devs to set up a default.nix in the directory).

Suggesting Edit: Install Holochain

Page URL: http://developer.holochain.org/docs/install/

As per holochain/holochain-rust#1760, this page needs a couple of updates IMO.

Firstly, on my computer with Manjaro Linux, I need to pipe curl https://nixos.org/nix/install with a shell command, otherwise it doesn't work (see the above issue for details). E.g., as I use zsh by default, I ran curl https://nixos.org/nix/install | zsh, other common ones would be piped with bash or sh.

Secondly, I got:

[jr@lm ~]$ nix-env --versioncopy
error: no operation specified
[jr@lm ~]$ nix-env --version
nix-env (Nix) 2.3.1

So LTM like it needs to be updated to nix-env --version.

Add additional social/community channels/links to the footer

Request:
Page: developer.holochain.org
Add: Mattermost at the top before or after Blog?
Link: Mattermost: https://chat.holochain.net/appsup/channels/app-dev
Add Telegram: http://t.me/channelHolo
Add Reddit: https://www.reddit.com/r/holochain/

Suggesting Edit: Hello Me Tutorial - Check your code discrepancies in another box

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/

The Check your Code box after the definition of show_person is also wrong (seperate box from the error reported in #154

Specifically - the show_output in the code constructed line by line is ...

function show_output(result, id) {
  var el = document.getElementById(id);
  var output = JSON.parse(result);
  el.textContent = ' ' + output.Ok;
}

But in the "Check your code box" its

// Render functions
function show_output(result, id) {
  var el = document.getElementById(id);
  var output = JSON.parse(result);
  if (output.Ok) {
    el.textContent = ' ' + output.Ok;
  } else {
    alert(output.Err.Internal);
  }
}

With extra error checking ...

Suggesting Edit: Get Involved

Page URL: http://developer.holochain.org/docs/get-involved/

1. Change: From: Connect and Contribute To: Connect and contribute
2. Update Twitter link: twitter.com/holochain

cc: @Klayemore

Suggesting Edit: Hello Me Tutorial - python call needs update

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/

Suggest changing the python invokation line from

python -m SimpleHTTPServer

to

python -m SimpleHTTPServer

Or if you use Python 3, use this command instead:

python -m http.server

(this is what you have in one of the other tutorials and works)

Add a link to Willems tutorial to site

https://medium.com/holochain/first-steps-writing-holochain-happs-with-rust-80ae111960e

link to old mattermost url in overview section

https://developer.holochain.org/start.html

link needs to go to .org instead of .net

Confusing explanations about `native_type` in first_steps

What is the URL of the page with the issue?

https://developer.holochain.org/guide/latest/first_steps.html#adding-some-entries

What specific instruction was incorrect, or did not work for you?

Take note of the native_type field of the macro which gives which Rust struct represents the entry type.
(see source)

The example above this line does not contain any native_type field, so I'm very confused and not sure what I should take note of.

Probably the code code updated and not the text or vis-versa?

In the new generated test code "config" has been renamed to "conductorConfig" causing the test to fail when sticking to the tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_test/

add google analytics to the site

Suggesting Edit: Install Holochain

Page URL: http://developer.holochain.org/docs/install/

when running hc --version I am receiving hc 0.0.34-alpha1

add emdash support

"Method not found". I'm doing "app/zome/method" format calls. All the doc pages regarding frontend interfaces are blank

Jimmy, [20 Jan 2019 19:28:50]:
...just dropped into the MatterMost chat, so we'll see there. Basically did the hc-rust todo list tutorial, got it running on a websocket server, but every call I make to it aside from "info/instances" returns "Method not found". I'm doing "app/zome/method" format calls.

and I was curious if any webhook RPC calls are documented anywhere aside from info/instances.

All the doc pages regarding frontend interfaces are blank

Though I know it's early in the process. I just assume they haven't been written yet.

Very early in the process myself, but so far it's not bad. It somewhat stinks that they changed to Rust/WebAssembly recently and invalidated most of the existing tutorials/sample apps in the process, but I understand the move, and ultimately it'll provide greater flexibility in the future. So I'm simultaneously having to learn Rust compared to other widely used languages. Though I think the design of the HC and the use of sharded DHTs and app specific crypto chains is a very cool concept.

Catalina

I'm opening this issue to investigate getting nix-shell to work on catalina. So far I can't find a working solution. It's not working for @dhtnetwork

Add link to dev camps

Suggesting Edit: Install Holochain

Page URL: http://developer.holochain.org/docs/install/
After running the script in Linux, it says:
"Installation finished! To ensure that the necessary environment
variables are set, either log in again, or type

~/.nix-profile/etc/profile.d/nix.sh"

However, nix.sh in this location is not an executable.. the script should chmod +x nix.sh first. And presumably the daemon version also in that directory.

make note of recommended process to open GH issues for troubleshooting

do this wherever someone is installing something.

Bonus: create an issue template

New docs website: button to edit a page directs to an issue

Steps to reproduce:

1. Go to a docs page, e.g. https://developer.holochain.org/docs/guide/conductors/
2. Click the edit button

I am redirected to a new GitHub issue with a template like so:

Expected/desired behaviour: to be redirected like on the previous site to be able to edit the source code for the page directly. This is particularly helpful for minor edits, which are not expected to need discussion.

Suggesting Edit: Hello Me Tutorial - discrepancy in first UI hello.js text box

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/

Oops - in the UI section the "Check your code" for hello.js bears almost no relationship to the code you had us type in above - there are a bunch of different functions, and even what is there has some changed syntax.

Has anyone tested the tutorials - I keep finding bugs in them ....

Suggesting Edit: Introduction

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/

Change to:

Welcome to the Core Concepts Tutorial Series. This is a set of tutorials that will take you through what you need to know to start building Holochain applications. They are designed to demonstrate the content of each Core Concept Article. The tutorials are progressive, so it’s best to complete them in order.

Start your journey with Hello Holo.

Update links on holochain.org website

Holochain.org home page
Change Request: Update links from Holochain proto to Holochain rust on the Holochain.org home page.

1. Holochain.org home page / Resources
   Update link from proto to rust
2. Holochain.org home page / Drop down menu
   Update Readme link from proto to rust

Suggesting Edit: Install Holochain

Page URL: http://developer.holochain.org/docs/install/

After the curl command (the next command) requires an update to the environment. The command line says this can be done by running ~/.nix-profile/etc/profile.d/nix.sh, except after the install this file needs to be chmod +x first. And this doesn't do it; you need to force the exports, the simplest way is to logout and log in again.

developer hdk docs, the upper left link to the top level of the docs is broken

In the developer hdk docs, the upper left link to the top level of the docs is broken: It should be something like https://developer.holochain.org/api/latest/hdk but instead points to https://developer.holochain.org/api/latest/index.html.

Suggesting Edit: Hello Holo Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_holo/

It's probably a better practice to create directory and file names without spaces.

It's an always good to frequently compile your app. -> It's always good to frequently compile your app.

zsh doesn't import nix-shell env vars

Work around is to add:
. $HOME/.nix-profile/etc/profile.d/nix.sh to ~/.zshrc.

Suggesting Edit: Hello Me Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/

Running into some strange compile errors while trying to follow on with this tutorial

And code:

#![feature(proc_macro_hygiene)]
#[macro_use]
extern crate hdk;
extern crate hdk_proc_macros;
extern crate serde;
#[macro_use]
extern crate serde_derive;
extern crate serde_json;
#[macro_use]
extern crate holochain_json_derive;

use hdk::holochain_core_types::{dna::entry_types::Sharing, entry::Entry};
use hdk::holochain_json_api::{error::JsonError, json::JsonString};
use hdk::{entry_definition::ValidatingEntryType, error::ZomeApiResult};
use hdk::holochain_persistence_api::{cas::content::Address};
use hdk_proc_macros::zome;

// see https://developer.holochain.org/api/latest/hdk/ for info on using the hdk library

#[derive(Serialize, Deserialize, Debug, DefaultJson, Clone)]
pub struct Person {
    name: String,
}

#[zome]
mod hello_zome {
    #[init]
    fn init() {
        Ok(())
    }

    #[validate_agent]
    pub fn validate_agent(validation_data: EntryValidationData<AgentId>) {
        Ok(())
    }

    #[zome_fn("hc_public")]
    fn hello_holo() -> ZomeApiResult<String> {
        Ok("Hello Holo".into())
    }

    #[entry_def]
    fn person_entry_def() -> ValidatingEntryType {
        entry!(
            name: "person",
            description: "Person to say hello to",
            sharing: Sharing::Private,
            validation_package: || {
                hdk::ValidationPackageDefinition::Entry
            },
            validation: | _validation_data: hdk::EntryValidationData<Person> {
                Ok(())
            }
        )
    }
    #[zome_fn("hc_public")]
    pub fn create_person(person: Person) -> ZomeApiResult<Address> {
        let entry = Entry::App("person".into(), person.into());
        let address = hdk::commit_entry(&entry)?
        Ok(address)
    }
}

Suggesting Edit: Building Holochain Apps - Bridging

Page URL: http://developer.holochain.org/docs/guide/bridging/

that allows a synchronous bidirectional transfer should be asynchronous

Suggesting Edit: Hello Me Tutorial - test fails in Firefox, works in Chrome

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/
Using the code from the latter hello.js Check-your-code
In Firefox, the result of

var address = document.getElementById('address_in').value;

is
" Address: QmaijZvaP2BKj5r14KLTaB2yF4V1hukkSg7cJG6nLtNFSL"
While in Chrome its
"QmaijZvaP2BKj5r14KLTaB2yF4V1hukkSg7cJG6nLtNFSL"

In Firefox it of course fails to retrieve that, while Chrome works fine.

I don't understand why Firefox behaves like this ... as the DOM looks like

<div>Address: <span id="address_output"> QmaijZvaP2BKj5r14KLTaB2yF4V1hukkSg7cJG6nLtNFSL</span></div>

But its 100% repeatable and will leave you to debug it ....

Suggesting Edit: Hello Me Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/

Think the initial diff for the refactored hello() function should change from

-      show_output(result),
+      show_output(result, id),

to

-      show_output(result),
+      show_output(result, 'output'),

The final code block for hello.js has it correct

Suggesting Edit: Hello World Tutorial - sim2h 9000 or 9001

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_world/

Which port should sim2h run on - consistently the "Check your code" examples are showing sim2h_url: 'wss://0.0.0.0:9001', and the page descriptions are saying sim2h_server -p 9000

Am I right in assuming this is a typo (examples seem to fail unless this is aligned), and if so which is correct ?

Feedback on Holochain Rust installation steps

Step 3 here: https://developer.holochain.org/start.html
You may have to restart terminal to be able to run that command.

Suggesting Edit: Hello Gui Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_gui/

When you say:

python -m SimpleHTTPServer

Or if you use Python 3, use this command instead:

python -m http.server

I think you can safely remove the python 2 recommendation because it is now deprecated.

Suggesting Edit: Hello Me Tutorial - bug in call to show_output ?

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/

This block looks wrong to me ...

function hello() {
  holochain_connection.then(({callZome, close}) => {
    callZome('test-instance', 'hello', 'hello_holo')({args: {}}).then(result =>
-      show_output(result),
+      show_output(result, id),
    );
  });
}

shouldn't id be output which is what the element to hold the output of the Hello call is called?

Can we add instructions on how to install a specific versions/releases of "hc" and "holochain"

What is the URL of the page with the issue?

https://developer.holochain.org/start.html - under heading: "Permanently install holochain tools (optional)"

What specific instruction was incorrect, or did not work for you?

As the holochain team releases new versions this creates breaking changes, during the devcamps we will choose to stick to a specific version of holochain and hc and would like this the ability to install specific versions via nix-env

What are the details of your platform?

N/A

Can we modify the holochain install documentation to what is suggested in the image below?

Update Windows Installation Instructions

• Need to correct in Step 5 for windows: replace: %HOME%/hc with %HOME%\hc

also, to address issues with installing zmq; here's what I did that worked:

• download and unzip lib files from https://github.com/holochain/holochain-rust/tree/develop/vendor/zmq
• edit environment variables in system properties to add: LIBZMQ_PREFIX to point to that directory of zmq lib files (I created this both as a user variable and a system variable; not sure that both are required)

Doing this created a error when running "hc --version" in cmd that said, "libzmq-v140-mt-4_2_0.dll not found" This file is found in the above reference directory in the "bin" folder.

So, I moved libzmq-v140-mt-4_2_0.dll to the same folder where hc.exe lives --> and huzzah! It now works.

Things I don't know:

• are the other zmq files still required? meaning, is it just libzmq-v140-mt-4_2_0.dll that's needed?
• I did follow the process for building the zmq libraries using visual studio 2017 (per the instructions sort of given on http://zeromq.org/intro:get-the-software#toc10 ) -- however, while this did build successfully in VS17, my cmd was still throwing the error mentioned above. I haven't tested doing this installation from scratch with just the above method.

add license key for template into HTML

will docs.rs be used for API documentation when holochain is published to crates.io soon?

seems recommendable to me, simplifies the work over here

Suggesting Edit: Networking

Page URL: http://developer.holochain.org/docs/guide/conductor_networking/

CTRL+F "Must be one of the following: 't', 'd', 'i', 'w', 'e' Each value"

->

This must be one of the following: 't', 'd', 'i', 'w', 'e'. Each value

n3h docs look like they could be improved, but that is too general a suggestion to create an issue for.

Suggesting Edit: Install Holochain

Page URL: http://developer.holochain.org/docs/install/

Note that if you will be running nix-shell https://holochain.love frequently, you may wish to set an alias, e.g. as instructed on this page.

Note that if you will be running `nix-shell https://holochain.love` frequently, you may wish to set an alias, e.g. as instructed on [this page](https://www.hostingadvice.com/how-to/set-command-aliases-linuxubuntudebian/).

remove "hc" crate from the list of API reference crates

Suggesting Edit: Hello Me Tutorial

Page URL: http://developer.holochain.org/docs/tutorials/coreconcepts/hello_me/

Test code says

sim2h_url: 'wss://0.0.0.0:9001',

But the server is run on 9000

sim2h_server -p 9000