Skip to content

Latest commit

 

History

History
154 lines (115 loc) · 6.95 KB

README.md

File metadata and controls

154 lines (115 loc) · 6.95 KB
Raw

Aztec Network Documentation

Documentation for the Aztec Network, built with docusaurus

You can view the latest successful build here: https://docs.aztec.network

Docusaurus

This website is built using Docusaurus 3, a modern static website generator.

Files

Here are the most relevant files you should be aware of:

  • .gitignore - This specifies which files Git should ignore when committing and pushing to remote repositories.
  • docusaurus.config.js - This is the configuration file for Docusaurus. You can manage the links in the header and footer, and site metadata here. A more in-depth introduction to this configuration file is available on the Docusaurus website and full documentation for the API is here.
  • package.json - This specifies the dependencies for the website and the commands that you can run with yarn.
  • sidebars.js - This specifies the sidebars for your documentation. The full documentation for this file is available on the Docusaurus website.
  • yarn.lock - This specifies the full dependencies for the website including the dependencies of the dependencies listed in package.json. Do not edit this file directly. Edit package.json instead, then run yarn as described above.

The .md files in the docs/ directory are the docs. See the Docusaurus website for the full documentation on how to create docs and to manage the metadata.

Installation

To install the dependencies and dev dependencies, run:

$ yarn

Development

Aztec docs pull some code from the rest of the repository. This allows for great flexibility and maintainability. Some documentation is also autogenerated.

For that reason, there's a preprocessing step. You can run that step ad-hoc with yarn preprocess or yarn preprocess:dev if you want it to stay running and watching for changes.

This step does the following:

  • Pulls the code from the source files using the #include macros explained below.
  • Autogenerates documentation using the scripts in the src file.
  • Puts the final documentation in a processed-docs folder.

Note

You likely want to benefit from webpack's hot reload, which allows you to immediately see your changes when you develop on the docs. For this reason, the yarn dev commands will add the ENV=dev environment variable, which makes docusaurus serve the docs folder instead of the processed docs. If you're making changes to included code or aztec.nr reference, you can run yarn docs instead.

Run locally

To run docusaurus development server and use hot reload (watch for changes), run:

$ yarn dev:local

Run remotely (on mainframe)

It's common for developers to work on codespaces or other remote targets. For this you need to expose your development server. This is common enough to be the default development command:

$ yarn dev

Build

To build the final version of the docs (which includes processes not present in dev, like broken links checking and minification), you can run:

$ yarn build

This command runs the preprocess command, generates static content into the build directory and can be served using any static contents hosting service.

Macros

As mentioned above, Aztec docs pull code from the source files. This makes it easy to include sections of the source code in tutorials and other examples.

This is done via macros which are processed in the process step described above.

#include_code

You can embed code snippets into a .md/.mdx file from code which lives elsewhere in the repo.

  • In your markdown file:
    • #include_code identifier path/from/repo/root/to/file.ts language
    • E.g. #include_code hello path/from/repo/root/to/file.ts typescript
    • See here for supported languages and the exact name to use for that language.
  • In the corresponding code delineate the code snippet with comments: 
    • some code
some code
// docs:start:hello
more code
more code
// this-will-error <-- you can use docusaurus highlighting comments.
this code will be highlighted red
more code
// highlight-next-line
this line will be highlighted
more code
// highlight-start
this line will be highlighted
this line will be highlighted
// highlight-end
more code
// docs:end:hello
more code
  • You can even include chunks of the same piece of code (with different highlighting preferences) into different parts of the docs: 
    •   some code
  some code
  // docs:start:hello:goodbye
  this code will appear in the 'hello' snippet and the 'goodbye' snippet.
  this code will appear in the 'hello' snippet and the 'goodbye' snippet.
  // this-will-error
  this code will be highlighted red in all snippets.
  // highlight-next-line:goodbye
  this line will be highlighted only in the 'goodbye' snippet.
  // highlight-start:goodbye:hello
  this line will be highlighted in both the `hello` and `goodbye` snippets
  this line will be highlighted in both the `hello` and `goodbye` snippets
  // highlight-end:goodbye
  this line will be highlighted only in the 'hello' snippet.
  // highlight-end:hello
  this code will appear in the 'hello' snippet and the 'goodbye' snippet.
  // docs:end:goodbye
  this code will appear only in the 'hello' snippet.
  // docs:end:hello
  some code
  some code
    • Somewhere in your markdown, you can then write:
      • #include_code hello path/from/repo/root/to/file.ts typescript
    • And somewhere else, you can write:
      • #include_code goodbye path/from/repo/root/to/file.ts typescript
  • You can add as a last optional parameter a comma-separated list of options to tweak the display of the code block, for example:
    • #include_code hello path/from/repo/root/to/file.ts typescript noTitle,noLineNumbers,noSourceLink
  • Ironically, we can't show you a rendering of these examples, because this README.md file doesn't support the #include_code macro!

See here for another way to include code, although this approach is flakier, so the above #include_code macro is preferred.

#include_aztec_version

This macros will be replaced inline with the current aztec packages tag, which is aztec-packages-v0.7.10 at the time of these writing. This value is sourced from .release-please-manifest.json on the project root.

Alternatively, you can also use the AztecPackagesVersion() js function, which you need to import explicitly:

import { AztecPackagesVersion } from "@site/src/components/Version";
<>{AztecPackagesVersion()}</>

Contributing

We welcome contributions from the community. Please review our contribution guidelines for more information.