From b1fb9dcd382070c7a24986ca7e94d039dc266498 Mon Sep 17 00:00:00 2001 From: liv Date: Mon, 7 Aug 2023 10:24:44 +0200 Subject: [PATCH] fix: use glob instead of walkdir --- Cargo.lock | 10 +- Cargo.toml | 4 +- tests/gallery/oranda_impl.rs | 71 +- tests/snapshots/gal_oranda-public.snap | 7060 ------------------------ 4 files changed, 37 insertions(+), 7108 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index cda1097b..58886d3c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1076,6 +1076,12 @@ version = "0.27.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b6c80984affa11d98d1b88b66ac8853f143217b399d3c74116778ff8fdb4ed2e" +[[package]] +name = "glob" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2fabcfbdc87f4758337ca535fb41a6d701b65693ce38287d856d1674551ec9b" + [[package]] name = "globset" version = "0.4.12" @@ -1438,10 +1444,12 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a0770b0a3d4c70567f0d58331f3088b0e4c4f56c9b8d764efe654b4a5d46de3a" dependencies = [ "console", + "globset", "lazy_static", "linked-hash-map", "regex", "similar", + "walkdir", "yaml-rust", ] @@ -1985,6 +1993,7 @@ dependencies = [ "console", "fs_extra", "futures-util", + "glob", "include_dir", "indexmap 1.9.3", "insta", @@ -2012,7 +2021,6 @@ dependencies = [ "tracing", "tracing-subscriber", "url", - "walkdir", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index b8128e4e..9c7a7875 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -58,8 +58,8 @@ oranda-generate-css = { version = "0.3.0-prerelease.4", path = "generate-css" } [dev-dependencies] assert_cmd = "2" assert_fs = "1.0.7" -insta = { version = "1.31.0", features = ["filters"] } -walkdir = "2.3.3" +insta = { version = "1.31.0", features = ["filters", "glob"] } +glob = "0.3.1" [build-dependencies] oranda-generate-css = { version = "0.3.0-prerelease.4", path = "generate-css" } diff --git a/tests/gallery/oranda_impl.rs b/tests/gallery/oranda_impl.rs index 6b8284c7..22a6660b 100644 --- a/tests/gallery/oranda_impl.rs +++ b/tests/gallery/oranda_impl.rs @@ -1,4 +1,3 @@ -use std::collections::BTreeMap; use std::sync::Mutex; use camino::{Utf8Path, Utf8PathBuf}; @@ -179,10 +178,9 @@ pub struct OrandaResult { } impl<'a> TestContext<'a, Tools> { - /// Run 'cargo dist build -aglobal' with the toml patched - /// and return paths to various files that were generated + /// Run `oranda build` with the JSON configuration that we provided which sets up our fake + /// workspace pub fn oranda_build(&self, test_name: &str) -> Result { - // build installers eprintln!("running oranda build..."); self.tools.oranda.output_checked(|cmd| cmd.arg("build"))?; @@ -245,47 +243,33 @@ impl OrandaResult { // We make a single uber-snapshot to avoid the annoyances of having multiple snapshots in one test let mut snapshots = String::new(); - Self::append_snapshot_dir(&mut snapshots, "public", self.public_dir.as_deref())?; - - let test_name = &self.test_name; - snapshot_settings_with_oranda_css_filter().bind(|| { - insta::assert_snapshot!(format!("{test_name}-public"), &snapshots); - }); - Ok(()) - } - - fn append_snapshot_dir( - out: &mut String, - name: &str, - src_path: Option<&Utf8Path>, - ) -> Result<()> { - // Skip snapshotting this folder if absent - let Some(src_path) = src_path else { + let Some(src_path) = &self.public_dir else { return Ok(()); }; - - let mut results = BTreeMap::new(); - - for entry in walkdir::WalkDir::new(src_path) { - let entry = entry.into_diagnostic()?; - if entry.file_type().is_file() { - let path = Utf8Path::from_path(entry.path()).expect("path wasn't utf8!?"); - let rel_path = path - .strip_prefix(src_path) - .expect("path's child wasn't its child!?") - .to_owned(); - let ext = rel_path.extension().unwrap_or_default(); - if ext == "html" { - results.insert(rel_path, path.to_owned()); - } + for path in glob::glob(&format!("{}/**/*.html", src_path)).unwrap() { + let path = path.unwrap(); + + let path = Utf8PathBuf::from_path_buf(path).unwrap(); + // We don't want to test another tool's output, so we filter out mdbook files. This + // is kind of a FIXME, the way we do this is very brittle, we should really be disabling + // mdbook from running altogether. + if !&path.to_string().contains("book") { + let rel_path = pathdiff::diff_utf8_paths(&path, src_path).unwrap(); + // Normalize Windows slashes to Unix slashes + let rel_path = rel_path.to_string().replace('\\', "/"); + Self::append_snapshot_file( + &mut snapshots, + &format!("public/{}", rel_path), + Some(path.as_path()), + ) + .unwrap(); } } - for (rel_path, path) in &results { - // normalize path to unix slashes when emitting to snapshot - let rel_path = rel_path.as_str().replace('\\', "/"); - Self::append_snapshot_file(out, &format!("{name}/{rel_path}"), Some(path))?; - } + let test_name = &self.test_name; + snapshot_settings_with_oranda_css_filter().bind(|| { + insta::assert_snapshot!(format!("{test_name}-public"), &snapshots); + }); Ok(()) } @@ -294,11 +278,8 @@ impl OrandaResult { name: &str, src_path: Option<&Utf8Path>, ) -> Result<()> { - // Skip snapshotting this file if absent - let Some(src_path) = src_path else { - return Ok(()); - }; - + // `insta::glob!` guarantees this path exists + let src_path = src_path.unwrap(); let src = axoasset::LocalAsset::load_string(src_path)?; Self::append_snapshot_string(out, name, &src) } diff --git a/tests/snapshots/gal_oranda-public.snap b/tests/snapshots/gal_oranda-public.snap index 8b15c0fd..e1ded029 100644 --- a/tests/snapshots/gal_oranda-public.snap +++ b/tests/snapshots/gal_oranda-public.snap @@ -372,7066 +372,6 @@ expression: "&snapshots" -================ public/book/404.html ================ - - - - - - Page not found - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Document not found (404)

-

This URL is invalid, sorry. Please use the navigation bar or search to continue.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/assets.html ================ - - - - - - Assets - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Adding static assets

-

If you reference static assets in your Markdown, you'll need to place them all inside a directory at the same level as -your project manifest file called static. This is because Oranda currently doesn't know about each indidivual asset, -and instead just copies the folder where they're contained.

-

In your Markdown, you'll need to refer to the assets in this directory. For example:

-
![An image from my amazing project](./static/project.png)
-
-

If you want to use a custom-named directory you can configure this in your oranda.json, like so:

-
{
-  "build": {
-    "static_dir": "assets"
-  }
-}
-
-

In this case the assets directory will be used instead of the default static directory.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/cli/build.html ================ - - - - - - build - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

oranda build

-

This command builds your oranda site. You can specify:

-
    -
  • The project root (--project-root), in case you want to build from another directory
    • -
  • The config path (--config-path), if your configuration file is not ./oranda.json
    • -
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/cli/dev.html ================ - - - - - - dev - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

oranda dev

-

This command basically combined oranda build and oranda serve, with the added benefit of watching for changes -and recompiling automatically. When you launch, what happens is this:

-
    -
  1. Oranda builds your site (unless you told it not to)
    2. -
  2. Oranda launches a server similar to oranda serve
    3. -
  3. Oranda starts watching its relevant files for changes, and will rerun the build process when something changes
    4. -
-

Oranda's build can have a lot of side-effects (reading/writing files, but also talking to the GitHub API), and as -such, we have to take care to only run the build process when relevant files change. These files are:

-
    -
  • Your project manifest files (Cargo.toml, package.json)
    • -
  • Your oranda configuration file
    • -
  • Any mdbook source files you may have
    • -
  • Your readme, and additional files specified in the configuration
    • -
  • Files immediately relevant to certain components oranda renders (funding, for example)
    • -
  • Any other paths you give it using --include-paths
    • -
-

This command also support several options:

-
    -
  • --port to set a custom port for the file server
    • -
  • --project-root to change the root directory from where your site will be built
    • -
  • --config-path to specify a custom path for your oranda config
    • -
  • --no-first-build to skip the first step mentioned above where oranda builds your site before starting the watch process
    • -
  • -i, --include-paths to specify custom paths for oranda to watch
    • -
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/cli/serve.html ================ - - - - - - serve - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

oranda serve

-

This command launches a small axum-powered server that serves your generated oranda site.

-

Importantly, this does not build your site for you. If it can't find a build in the public/ directory, -it will error and exit. You can set the port for the server to be launched using the --port option.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/cli.html ================ - - - - - - Command Line - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Command Line

-

Oranda currently has three subcommands that work in similar, but nuanced ways.

- -

Oranda supports some common options on each command:

-
    -
  • --verbose. This controls the verbosity level for logs.
    • -
  • --output-format. If you want JSON for processing it with a machine, this is where you'd toggle it.
    • -
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/additional-pages.html ================ - - - - - - Additional Pages - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Additional Pages

-

If you have extra Markdown files you'd like to link directly as root pages on your generated website, you can -use the additional_pages option to list them.

-

The option's format is an object with the human-readable page name as keys, and the path to the file as values. Example:

-
{
-  "build": {
-    "additional_pages": {
-      "Another page": "./AnotherFile.md"
-    }
-  }
-}
-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/analytics.html ================ - - - - - - Analytics - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Analytics

-

oranda supports automatically inserting the correct analytics snippet your provider into your generated pages.

-

Right now we support the following analytics providers:

- -

To add any of these, add the required configuration under the analytics key:

-

Google Analytics

-
{
-  "marketing": {
-    "analytics": {
-      "google_analytics": {
-        "tracking_id": "String"
-      }
-    }
-  }
-}
-
-

Plausible

-
{
-  "marketing": {
-    "analytics": {
-      "plausible": {
-        "domain": "String",
-        "script_url": "Optional string for self hosted"
-      }
-    }
-  }
-}
-
-

Fathom

-
{
-  "marketing": {
-    "analytics": {
-      "fathom": {
-        "site": "String"
-      }
-    }
-  }
-}
-
-

Unami

-
{
-  "marketing": {
-    "analytics": {
-      "unami": {
-        "website": "String",
-        "script_url": "String"
-      }
-    }
-  }
-}
-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/artifacts.html ================ - - - - - - Artifacts & cargo-dist - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Artifacts & cargo-dist

-

oranda has first-class support for handling releases generated by cargo-dist. It can even detect the user's platform and recommend the best installer/archive to use!

-

Artifact settings are managed in the artifacts key in your oranda config. This is what an example config looks like:

-
{
-  "components": {
-    "artifacts": {
-      "package_managers": {
-        "preferred": {
-          "npm": "npm install @axodotdev/oranda --save-dev",
-          "crates.io": "cargo install oranda --locked --profile=dist",
-        },
-        "additional": {
-          "npx": "npx @axodotdev/oranda",
-          "binstall": "cargo binstall oranda"
-        }
-      }
-    }
-  }
-}
-
-

Enabling cargo-dist

-

oranda will automatically attempt to find a cargo-dist config in your Cargo.toml. If you want to force disable this, -set components.artifacts.cargo_dist to false. Once oranda determines that cargo-dist support should be enabled, -the following will happen:

-
    -
  • oranda will attempt to find GitHub releases generated by cargo-dist
    • -
  • A new "Install" page will be generated, containing all artifacts and installers for the latest version
    • -
  • A section to quickly install the latest release for the user's current platform will be added to the homepage
    • -
-

Enabling arbitrary GitHub release support

-

Even if you don't have cargo-dist set up, oranda can attempt to glean information about your supported targets and -OSes from your GitHub release artifacts. It will attempt to do this if it can find any releases associated with your -repository. It does this by trying to see if it can recognize any known target triples from your filenames, so for example, -it will recognize mytool-aarch64-apple-darwin.tar.gz. If you would like to completely disable this, set -components.artifacts to false (we may offer a more fine-grained setting for this in the future).

-

Adding package manager installation instructions

-

You can add custom installation instructions for package managers or package manager-esque methods using the -components.artifacts.package_managers key. These are broken up into two sections:

-
    -
  • components.artifacts.package_managers.preferred - methods that you want to be recommended on the front page install -widget
    • -
  • components.artifacts.package_managers.additional - methods that should only show up on the dedicated "install" page
    • -
-

All package manager entries are currently treated as "cross-platform", meaning they'll show up in the install widget for -any platform you support. We're aware of this limitation, and will likely expand support for this in the future.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/changelog.html ================ - - - - - - Changelogs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Changelogs

-

oranda supports reading your project's changelogs from GitHub releases. You can enable this by setting components.changelog to true:

-
{
-  "components": {
-    "changelog": true
-  }
-}
-
-

This will result in a new "Changelog" page being generated. Changelogs are pulled directly from GitHub releases. If -you're using the cargo-dist integration, oranda will attempt to parse a CHANGELOG.md-like file for -the changelogs instead.

-
-

NOTE: We're working on getting changelog parsing from a CHANGELOG.md file as a default feature, without requiring -use of cargo-dist!

-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/funding.html ================ - - - - - - Funding - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Funding page

-

Oranda has the capability of reading information from your GitHub funding file, and -automatically writing a page based on it. Unless you disable it by setting components.funding to false -in the oranda config file, oranda will search your project for -a .github/FUNDING.yml file, and generate a page based off of it. You can read -more about the format of this file on GitHub's docs.

-

Oranda will display your different sponsor/funding links next to each other, but -if you have a "main" funding option, you can set the following configuration setting:

-
{
-  "components": {
-    "funding": {
-      "preferred_funding": "github"
-    }
-  }
-}
-
-

Make sure this key corresponds to one of the possible entries in the FUNDING.yml -file.

-

If you want to display additional information or context, oranda can also include -the contents of a top-level funding.md Markdown file. Its contents will be translated -into HTML and displayed on the Funding page as well.

-

Both of the YAML and Markdown file paths can be customized as such:

-
{
-  "components": {
-    "funding": {
-      "md_path": "myfunding.md",
-      "yml_path": "misc/funding.yml"
-    }
-  }
-}
-
-
-

oranda's funding parsing and site generation are currently an experiment into how -to better integrate common funding methods into your tools' websites. If you have -any feedback on how we could do things better, let us know on -Discord or GitHub!

-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/mdbook.html ================ - - - - - - mdbook support - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

mdbook support

-

oranda can generate mdbooks for you. If you've already worked with mdbook, it's as simple as pointing oranda -at your book directory using the mdbook.path option:

-
{
-  "components": {
-    "mdbook": {
-      "path": "./docs"
-    }
-  }
-}
-
-

This will cause oranda to automatically recompile your book for you, which will be served at the yoursite/book/ URL. -oranda dev will also be watching this directory.

-

mdbook quickstart

-

If this is the first time you're working with mdbook, these are the minimal steps you'd need before editing the oranda config. -After you've installed the mdbook tool, you can generate a new book scaffold:

-
mdbook init docs # replace docs with your preferred directory
-
-

You can either use oranda dev or mdbook serve docs/ to have a preview for your mdbook.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/social.html ================ - - - - - - Social - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Social

-

In order to help with SEO, there are a couple of options you can use.

-
{
-  "marketing": {
-    "social": {
-      "image": "used as the share image for social media",
-      "image_alt": "alt for said image",
-      "twitter_account": "twitter account for the website"
-    }
-  }
-}
-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/theme/previews.html ================ - - - - - - Theme Previews - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Theme Previews

-

Here you can see what themes look like without having to set up oranda yourself.

-

These previews are generated by running oranda on itself.

-

Dark (default)

-

dark theme preview

-

Light

-

light theme preview

-

Axo Dark

-

axo dark theme preview

-

Axo Light

-

axo light theme preview

-

Hacker

-

hacker theme preview

-

Cupcake

-

cupcake preview

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/theme.html ================ - - - - - - Theming - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Theming

-

Predefined themes

-

Oranda comes with six default themes:

-
    -
  • Light
    • -
  • Dark
    • -
  • Axo Light (axo_light or axolight)
    • -
  • Axo Dark (axo_dark or axodark)
    • -
  • Hacker
    • -
  • Cupcake
    • -
-

You can change the theme by adding the styles.theme key to your oranda.json:

-
{
-  "styles": {
-    "theme": "hacker"
-  }
-}
-
-

Dark is the default theme.

-

Customizing Themes

-

Themes can be further customized by adding extra CSS.

-

Additional CSS can be added using the styles.additional_css key.

-
{
-  "styles": {
-    "additional_css": ["./local/file.css", "http://www.remote.dev/file.css"]
-  }
-}
-
-
-

Note: Remote files will be copied and the copy served locally, so once a link is updated, the site must be regenerated for changes to take effect.

-
-

Adding CSS

-

Oranda's CSS makes use of cascade layers to scope CSS and make it simpler to override styles. To override themed styles, say on a <p> element, place it inside a layer called overrides.

-
@layer overrides {
-  p {
-    color: aquamarine;
-  }
-}
-
-

Alternately, CSS that is not defined within a layer has precedence over all layered CSS, so this will also work.

-
p {
-  color: aquamarine;
-}
-
-

Dark vs. Light

-

When the dark theme is selected, a dark class is added to the page, and styles to be applied in dark mode only can include this selector. For instance,

-
.dark p {
-  color: aquamarine;
-}
-
-

Will create paragraphs colored aquamarine in dark mode only.

-

Adding Classes

-

When there are specific elements you would like to add to your pages, these can be added into Markdown files as raw HTML with class selectors that you can target with your CSS.

-
<!-- README.md -->
-
-## A Different Kind of Box
-
-<div class="my-border-class">
-  <p>An outlined box</p>
-</div>
-
-
.my-border-class {
-  padding: 1rem;
-  border: 6px dotted seagreen;
-}
-
-

Creating a New Theme

-

Currently, to create a new theme, you need to follow the directions above in "Customizing Themes" and overwrite the given CSS. We recommend continuing the layer approach and placing overrides in the overrides layer and then adding a new named layer for your theme.

-

The ability to add a different theme directly will be included in future releases. Following the layers approach will make it simpler to transition your theme.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration/workspaces.html ================ - - - - - - Workspaces - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Workspaces

-

oranda supports building multiple sites at once (referred to as building in a "workspace"). To control this behavior, -you can create a oranda-workspace.json file inside your workspace root. Running an oranda command will pick up this -file, and build the workspace members accordingly.

-

The reason why this is a separate file, and not part of the oranda.json file is to avoid confusing between nonvirtual -workspace root members (meaning if a workspace root also contains a site/package of some kind). By putting your workspace -configuration in a separate file, you can still have an oranda site at the same directory level, without any problems.

-
-

NOTE: Workspace functionality will not be enabled if the oranda-workspace.json file doesn't exist!

-
-

A workspace configuration file looks something like this:

-
{
-  "workspace": {
-    "name": "My Workspace",
-    "members": [
-      {
-        "slug": "projectone",
-        "path": "./project-one"
-      },
-      {
-        "slug": "project_two",
-        "path": "./project-two"
-      }
-    ]
-  }
-}
-
-

When ran with oranda build, this will produce two oranda sites, one at /projectone, and one at /project_two. oranda -will consider each separate project's oranda.json file (should it exist).

-

You can additionally pass down keys you'd like to be set for each member project:

-
{
-  "workspace": {
-    // same as above
-  },
-  "styles": {
-    "theme": "hacker" // set every site's theme to hacker
-  }
-}
-
-

Individual workspace member configs will still override what's set here, though. Also, every key will be passed down, -including ones that don't make a lot of sense to be the same in multiple projects (for example package manager -configuration).

-

Building a workspace will also generate a nice workspace index page that can be used to provide an overview over the -workspace's members, as well as some quick info and metadata.

-

List of workspace configuration keys

-
    -
  • name - set the overarching workspace name
    • -
  • auto - enable workspace autodetection
    • -
  • generate_index - disable generating a workspace index page
    • -
  • members - list the workspace members - -
    • -
-

name

-
-

Added in version 0.3.0.

-
-

Set the overarching workspace name. This is optional, and will fall back to "My Oranda Workspace" if not set (not very -intuitive, I know).

-

auto

-
-

Added in version 0.3.0.

-
-

Enables workspace autodetection if set to true. This will cause oranda to attempt to find any Cargo or NPM workspaces -under the current directory, and to attempt to build all of its members (all members must therefore have at least a -readme file). Members manually listed under the members key override these automatically detected workspace members.

-

generate_index

-
-

Added in version 0.3.0.

-
-

If set to false, does not generate a workspace index page that links between all workspace members. Use this if you -just want to use oranda's workspace functionality to build multiple unrelated sites in one go.

-

members

-
-

Added in version 0.3.0.

-
-

An array of objects representing the workspace members.

-

members.slug

-
-

Added in version 0.3.0.

-
-

The URL-safe slug this page will be built at. This needs to be something that can be parsed as a URL, as well as a folder -name on your target system (because oranda is a static site generator, after all).

-

members.path

-
-

Added in version 0.3.0.

-
-

The path to the page source. Point this to the same directory that the oranda.json would be in.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/configuration.html ================ - - - - - - Configuration - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Configuration

- -
-

📦 = automatically collected from your package metadata!

-
-

oranda is designed to work with no configuration- for projects with a -package.json or Cargo.toml, oranda will grab the project metadata it needs -from your project manifest file. It can also infer a lot of the things it wants to -render from your already existing environment.

-

If you project has both a Cargo.toml and a package.json we recommend defining -project metadata fields like name in your oranda.json.

-

Manifest file: oranda.json

-

If you'd like to customize your project you can do so in a oranda.json file.

-

For example:

-
{
-  "build": {
-    "path_prefix": "oranda"
-  },
-  "styles": {
-    "theme": "axodark",
-    "favicon": "https://www.axo.dev/favicon.ico"
-  },
-  "marketing": {
-    "social": {
-      "image": "https://www.axo.dev/meta_small.jpeg",
-      "image_alt": "axo",
-      "twitter_account": "@axodotdev"
-    },
-    "analytics": {
-      "plausible": {
-        "domain": "opensource.axo.dev"
-      }
-    }
-  },
-  "components": {
-    "changelog": true,
-    "artifacts": {
-      "package_managers": {
-        "preferred": {
-          "npm": "npm install @axodotdev/oranda --save-dev",
-          "cargo": "cargo install oranda --locked --profile=dist"
-        },
-        "additional": {
-          "npx": "npx @axodotdev/oranda",
-          "binstall": "cargo binstall oranda",
-          "nix-env": "nix-env -i oranda",
-          "nix flake": "nix profile install github:axodotdev/oranda"
-        }
-      }
-    }
-  }
-}
-
-
-

NOTE: All paths in oranda.json are relative to the oranda.json file.

-
-

Workspace manifest file: oranda-workspace.json

-
-

Added in version 0.3.0.

-
-

oranda supports building multiple sites at once (referred to as building in a "workspace"). To control this behavior, -you can create a oranda-workspace.json file inside your workspace root. Running an oranda command will pick up this -file, and build the workspace members accordingly.

-

The workspace file supports all other oranda config keys, which will be passed down to each workspace members.

-

Read more about workspaces

-

Project Configuration

-

name

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest name field
    • -
-

Your project's name.

-

version

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest version field.
    • -
-

Your project's current version.

-

description

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest description field
    • -
-

Your project's description.

-

homepage

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest homepage field
    • -
-

Your project's homepage.

-

repository

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest repository field
    • -
-

Your project's Git repository.

-

readme_path

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: A variation of the standard README.md
    • -
-

The path to your project's readme file.

-

license

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest license field.
    • -
-

Your project's license.

-

Build Configuration

-

dist_dir

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: public/
    • -
-

The directory where your static files will be output to. This must be relative to the oranda.json file.

-

static_dir

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: static/
    • -
-

Static content that oranda will copy to its output folder. This must be relative to the oranda.json file.

-

path_prefix

-
-

Added in version 0.1.0.

-
-

If you're hosting oranda on a nested path (e.g. mysite.cool/myproject), you should set path_prefix to -myproject in your configuration in order for oranda to generate correct links.

-

additional_pages

-
-

Added in version 0.1.0.

-
-

An object of additional Markdown pages that you'd like to be included. All of these will appear in the site header.

-

More information

-

Marketing Configuration

-

analytics

-
-

Added in version 0.1.0.

-
-

Configuration for page analytics.

-

More information

-

social

-
-

Added in version 0.1.0.

-
-

Options useful for SEO features.

-

More information

-

Style Configuration

-

theme

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: dark
    • -
-

Choose which built-in theme to use.

-

More information

-

additional_css

-
-

Added in version 0.1.0.

-
-

Add extra CSS to your pages' header.

-

More information

-

oranda.css_version

-
-

Added in version 0.1.0.

-
-

Specify a version of the embedded oranda CSS. This can be used to opt into newer CSS releases that don't have -an oranda release associated with them yet. (Internally, this looks for a oranda.css release artifact on the given -tag in the axodotdev/oranda GitHub repository)

- -
-

Added in version 0.1.0.

-
-

Path to a custom logo to be shown in your website header.

-

favicon

-
-

Added in version 0.1.0.

-
-

Path to a custom favicon.

-

Components Configuration

-

artifacts

-
-

Added in version 0.1.0.

-
-

Configuration for enabling downloadable artifacts, as well as the cargo-dist integration.

-

More information

-

mdbook or md_book

-
-

Added in version 0.1.0.

-
-

Configuration for mdbook.

-

More information

-

changelog

-
-

Added in version 0.1.0.

-
-

Enable changelog generation.

-

More information

-

funding

-
-

Added in version 0.1.0.

-
-

Allows you to tweak or disable oranda's funding page.

-

More information

-

Configuration before 0.1.0

-

Before version 0.1.0 (the last stable version was/is 0.0.3, the last prerelease was/is 0.1.0-prerelease7), the -configuration format looked like this:

-
{
-  "name": "oranda",
-  "description": "generate static sites for your dev tools",
-  "dist_dir": "oranda_out",
-  "homepage": "https://oranda.axo.dev",
-  "static_dir": "static",
-  "no_header": false,
-  "readme_path": "dev/README.md",
-  "repository": "https://github.com/axodotdev/oranda",
-  "additional_pages": {
-    "Another page": "dev/additional.md"
-  },
-  "favicon": "https://www.axo.dev/favicon.ico",
-  "analytics": {
-    "plausible": {
-      "domain": "tools.axo.dev/oranda"
-    }
-  },
-  "social": {
-    "image": "https://www.axo.dev/meta_small.jpeg",
-    "image_alt": "axo",
-    "twitter_account": "@axodotdev"
-  },
-  "artifacts": {
-    "cargo_dist": true
-  },
-  "logo": "assets/oranda.png",
-  "license": "MIT OR Apache-2.0",
-  "mdbook": false,
-  "path_prefix": "oranda",
-  "styles": {
-    "theme": "axo_dark"
-  },
-  "funding": {
-    "preferred_funding": "github"
-  },
-  "changelog": true
-}
-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/contributing.html ================ - - - - - - Contributing - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Contributing

-

Here's some helpful tips for contributing.

-

Auto-recompiling based on source changes

-

If you're working on oranda and you want to rebuild both oranda itself and your preview site when stuff changes, -this is the command to keep in mind (assuming you have cargo-watch installed):

-
cargo watch -x "run dev"
-
-

On some platforms, apparently images also get recompiled and picked up by cargo-watch:

-
cargo watch -x "run dev" --ignore "*.png"  --ignore "*.jpg"
-
-

...plus working on the CSS

-

As long as you're working with a development build of oranda (by running cargo run without the --release flag), -oranda will automatically download a version of the Tailwind compiler and compile the CSS from your -local checkout for you.

-

oranda dev doesn't automatically reload on CSS changes (because it's meant to be used by users), -but you can include the CSS directory manually like such:

-
cargo run dev -i oranda.css/css/
-
-

Updating syntax highlighting languages

-

We use syntect to support syntax highlighting in Markdown code blocks. If you want to add support for a new language -that's not included in syntect's default set of languages or the ones oranda provides, you'll need to extend the -oranda::site::markdown::syntax_highlight::dump_syntax_themes function to load your new .sublime-syntax file from disk -and to include it in our syntax set dump. This function, once adjusted, only needs to be ran once manually, by including -it anywhere in the call path of the application (I recommend somewhere close to the top of the build CLI function).

-

Converting from .tmLanguage

-

syntect accepts .sublime-syntax files, but Sublime Text can also accept .tmLanguage (TextMate syntax bundles) files, -so sometimes we need to convert from one to the other. Thankfully, the Sublime Text editor has a built-in feature for this. -Here's what you need to do:

-
    -
  1. Download and install Sublime Text
    2. -
  2. In Sublime Text, from the menu, select Tools -> Developer -> New Syntax...
    3. -
  3. This puts you in your Packages/User folder. Paste your tmLanguage file contents and save as <yourlang>.tmLanguage.
    4. -
  4. Next, you should be able to run Tools -> Developer -> New Syntax from .tmLanguage...
    5. -
  5. This opens a new tab with the converted output. Save and copy it or paste it into a new file in oranda. Profit!
    6. -
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/hosting.html ================ - - - - - - Hosting - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Hosting

-

On GitHub pages

-

When hosting on Github pages, it is often the case that your site will be served from a non-root url such as myorg.github.io/reponame.

-

If you are serving your site from this style of URL, you'll need to add the reponame as a path_prefix to your Oranda config. This will allow oranda to properly configure all chlid links (such as images or additional pages) of your page to be properly name spaced.

-

Let's say your website is hosted at https://myorg.github.io/reponame/, to fix the links, add the following to your oranda.json

-
{
-  "build": {
-    "path_prefix": "reponame"
-  }
-}
-
-

Using GitHub Actions

-

You can set up a simple workflow to automatically do this GitHub Pages deploy for you. Take a look at Oranda's own -web.yml file for reference:

-
# Workflow to build your docs with oranda (and mdbook)
-# and deploy them to Github Pages
-name: Web deploy
-
-# We're going to push to the gh-pages branch, so we need that permission
-permissions:
-  contents: write
-
-# What situations do we want to build docs in?
-# All of these work independently and can be removed / commented out
-# if you don't want oranda/mdbook running in that situation
-on:
-  # Check that a PR didn't break docs!
-  #
-  # Note that the "Deploy to Github Pages" step won't run in this mode,
-  # so this won't have any side-effects. But it will tell you if a PR
-  # completely broke oranda/mdbook. Sadly we don't provide previews (yet)!
-  pull_request:
-
-  # Whenever something gets pushed to main, update the docs!
-  # This is great for getting docs changes live without cutting a full release.
-  #
-  # Note that if you're using cargo-dist, this will "race" the Release workflow
-  # that actually builds the Github Release that oranda tries to read (and
-  # this will almost certainly complete first). As a result you will publish
-  # docs for the latest commit but the oranda landing page won't know about
-  # the latest release. The workflow_run trigger below will properly wait for
-  # cargo-dist, and so this half-published state will only last for ~10 minutes.
-  #
-  # If you only want docs to update with releases, disable this one.
-  push:
-    branches:
-      - main
-  
-  # Whenever a workflow called "Release" completes, update the docs!
-  #
-  # If you're using cargo-dist, this is recommended, as it will ensure that
-  # oranda always sees the latest release right when it's available. Note
-  # however that Github's UI is wonky when you use workflow_run, and won't
-  # show this workflow as part of any commit. You have to go to the "actions"
-  # tab for your repo to see this one running (the gh-pages deploy will also
-  # only show up there).
-  workflow_run:
-    workflows: ["Release"]
-    types:
-      - completed
-
-# Alright, let's do it!
-jobs:
-  web:
-    name: Build and deploy site and docs
-    runs-on: ubuntu-latest
-    steps:
-      # Setup
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: swatinem/rust-cache@v2
-
-      # Install and run oranda (and mdbook)
-      # This will write all output to ./public/ (including copying mdbook's output to there)
-      - name: Install and run oranda
-        run: |
-          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/latest/download/oranda-installer.sh | sh
-          oranda build
-
-      # Deploy to our gh-pages branch (making it if it doesn't exist)
-      # the "public" dir that oranda made above will become the root dir
-      # of this branch.
-      #
-      # Note that once the gh-pages branch exists, you must
-      # go into repo's settings > pages and set "deploy from branch: gh-pages"
-      # the other defaults work fine.
-      - name: Deploy to Github Pages
-        uses: JamesIves/github-pages-deploy-action@v4.4.1
-        # ONLY if we're on main (so no PRs or feature branches allowed!)
-        if: ${{ github.ref == 'refs/heads/main' }}
-        with:
-          branch: gh-pages
-          # Gotta tell the action where to find oranda's output
-          folder: public
-          token: ${{ secrets.GITHUB_TOKEN }}
-          single-commit: true
-
-

Elsewhere

-

oranda is, effectively, a static site generator. It outputs HTML, CSS and JavaScript files. These can all be hosted on a -looooot of different platforms, in fact, too many for us to enumerate here! You can use Vercel, Netlify, any GitHub pages -competitor, or you can plop it on your own server that runs nginx, Apache httpd, Caddy, or anything else!

-

You can, in fact, also use the CI example linked above and modify it to deploy to different platforms. If you do, -we'd love to hear about it!

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/index.html ================ - - - - - - Introduction - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Introduction

-

Oranda is a tool for generating beautiful landing pages for your projects.

-

It can:

-
    -
  • Automagically generate a webpage based off your project readme file
    • -
  • Include arbitrary Markdown pages
    • -
  • Generate mdbook books for you
    • -
  • Integrate with cargo-dist to show downloadable and installable artifacts
    • -
  • Provide integration with several web analytics providers
    • -
-

and more!

-

This is the oranda documentation, where we explain how to use the tool in detail. Use the -sidebar to the left to navigate between pages.

-
-

Caveat emptor! oranda is still alpha-quality software! Things might change in a breaking way, especially -the configuration format (although we're working hard on stabilizing it)

-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/install.html ================ - - - - - - Install - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Install

-

There's lots of ways to install oranda!

-

The Quickest Way

-

On the oranda website, there's a one-liner command you can execute for your -OS that'll download and install oranda for you, without any further hassle!

-

Install Prebuilt Binaries With cargo-binstall

-
cargo binstall oranda
-
-

Build From Source With Cargo

-
cargo install oranda --locked --profile=dist
-
-
-

--profile=dist is the profile we build our shippable binaries with, it's optional.

-

--locked asks Cargo to respect the lockfile, improving build reproducibility at the -the cost of not getting any bugfixes from newer releases of its dependencies.

-
-

Download Prebuilt Binaries From Github Releases

-

See The Latest Release!

-

Install With NPM

-
npm install oranda
-
-

Install With Nix

-

oranda is available in nixpkgs, and also as a nix flake. This installer is currently experimental, so we don't recommend you use it in production workflows.

-

On a system with nix installed, you can run

-
nix-env -i oranda
-
-

or to install from GitHub using the flake,

-
nix profile install github:axodotdev/oranda
-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/introduction.html ================ - - - - - - Introduction - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Introduction

-

Oranda is a tool for generating beautiful landing pages for your projects.

-

It can:

-
    -
  • Automagically generate a webpage based off your project readme file
    • -
  • Include arbitrary Markdown pages
    • -
  • Generate mdbook books for you
    • -
  • Integrate with cargo-dist to show downloadable and installable artifacts
    • -
  • Provide integration with several web analytics providers
    • -
-

and more!

-

This is the oranda documentation, where we explain how to use the tool in detail. Use the -sidebar to the left to navigate between pages.

-
-

Caveat emptor! oranda is still alpha-quality software! Things might change in a breaking way, especially -the configuration format (although we're working hard on stabilizing it)

-
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/print.html ================ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Introduction

-

Oranda is a tool for generating beautiful landing pages for your projects.

-

It can:

-
    -
  • Automagically generate a webpage based off your project readme file
    • -
  • Include arbitrary Markdown pages
    • -
  • Generate mdbook books for you
    • -
  • Integrate with cargo-dist to show downloadable and installable artifacts
    • -
  • Provide integration with several web analytics providers
    • -
-

and more!

-

This is the oranda documentation, where we explain how to use the tool in detail. Use the -sidebar to the left to navigate between pages.

-
-

Caveat emptor! oranda is still alpha-quality software! Things might change in a breaking way, especially -the configuration format (although we're working hard on stabilizing it)

-
-

Install

-

There's lots of ways to install oranda!

-

The Quickest Way

-

On the oranda website, there's a one-liner command you can execute for your -OS that'll download and install oranda for you, without any further hassle!

-

Install Prebuilt Binaries With cargo-binstall

-
cargo binstall oranda
-
-

Build From Source With Cargo

-
cargo install oranda --locked --profile=dist
-
-
-

--profile=dist is the profile we build our shippable binaries with, it's optional.

-

--locked asks Cargo to respect the lockfile, improving build reproducibility at the -the cost of not getting any bugfixes from newer releases of its dependencies.

-
-

Download Prebuilt Binaries From Github Releases

-

See The Latest Release!

-

Install With NPM

-
npm install oranda
-
-

Install With Nix

-

oranda is available in nixpkgs, and also as a nix flake. This installer is currently experimental, so we don't recommend you use it in production workflows.

-

On a system with nix installed, you can run

-
nix-env -i oranda
-
-

or to install from GitHub using the flake,

-
nix profile install github:axodotdev/oranda
-
-

Quickstart

-

After you've installed oranda, it's time to give it a spin. Make sure you can execute the -oranda command, its output should look something like this:

-
$ oranda
-🎁 generate beautiful landing pages for your projects
-
-Usage: oranda [OPTIONS] <COMMAND>
-
-Commands:
-build
-dev
-serve
-help Print this message or the help of the given subcommand(s)
-
-Options:
--h, --help Print help (see more with '--help')
--V, --version Print version
-
-GLOBAL OPTIONS:
---verbose <VERBOSE> How verbose logging should be (log level) [default: warn] [possible values:
-off, error, warn, info, debug, trace]
---output-format <OUTPUT_FORMAT> The format of the output [default: human] [possible values: human, json]
-
-
-

Basic Setup

-

oranda is designed to be a tool you can simply drop into an existing project. For the purposes of this -guide, we're going to use minimal-axolotlsay, a simple CLI project, but you can use one of your own -projects, or even set up a new one from scratch! The only hard requirement oranda has is for your -project to have a readme file (README.md).

-

The easiest way to get a feedback loop going with oranda is to move into the directory and run oranda dev:

-
git clone https://github.com/axodotdev/minimal-axolotlsay
-cd minimal-axolotlsay
-oranda dev
-
-

oranda dev is a command that will automatically recompile your oranda build when you change -one of the files relevant to it. It also launches a file server that'll allow you to look at the output - -if you open localhost:7979, you'll see something like this:

-

an image of the default oranda output when ran on axolotlsay

-

oranda has picked up on our readme file and converted it into a static page! How nice!

-

minimal-axolotlsay also has integration with cargo-dist already set up - a powerful way to streamline -cross-platform releases of applications. Since oranda and cargo-dist integrate, oranda already knows -about our cargo-dist releases, and automatically shows a widget and page to download the latest binaries.

-

How does oranda know where our repository is? It extracts the repository key from our Cargo.toml file! -oranda can do this for Rust and JavaScript/Node.js-based projects at the moment. This way, you don't need to -explicitly specify a lot of info you may already be keeping elsewhere.

-

Beyond the Basics

-

If we want to work with the more advanced features that oranda offers, we'll have to create a configuration file. -The default location of this file is oranda.json in the same directory where your project manifest is located. -You can view a full reference of the configuration schema here. Let's start by making the simplest and highest impact change: telling oranda that our project has changelogs that it should make pages for!

-
{
-  "components": {
-    "changelog": true
-  }
-}
-
-

If you now build again (you may have to restart oranda dev since we added a new file to watch), it should look like this:

-

an image of oranda with changelogs enabled

-

oranda pulled our project's releases from GitHub automatically, without us having to specify any further configuration -than enabling the changelog setting!

-

Further Steps

-

For more specific configuration, check out the configuration page and its sub-pages.

-

Hosting

-

On GitHub pages

-

When hosting on Github pages, it is often the case that your site will be served from a non-root url such as myorg.github.io/reponame.

-

If you are serving your site from this style of URL, you'll need to add the reponame as a path_prefix to your Oranda config. This will allow oranda to properly configure all chlid links (such as images or additional pages) of your page to be properly name spaced.

-

Let's say your website is hosted at https://myorg.github.io/reponame/, to fix the links, add the following to your oranda.json

-
{
-  "build": {
-    "path_prefix": "reponame"
-  }
-}
-
-

Using GitHub Actions

-

You can set up a simple workflow to automatically do this GitHub Pages deploy for you. Take a look at Oranda's own -web.yml file for reference:

-
# Workflow to build your docs with oranda (and mdbook)
-# and deploy them to Github Pages
-name: Web deploy
-
-# We're going to push to the gh-pages branch, so we need that permission
-permissions:
-  contents: write
-
-# What situations do we want to build docs in?
-# All of these work independently and can be removed / commented out
-# if you don't want oranda/mdbook running in that situation
-on:
-  # Check that a PR didn't break docs!
-  #
-  # Note that the "Deploy to Github Pages" step won't run in this mode,
-  # so this won't have any side-effects. But it will tell you if a PR
-  # completely broke oranda/mdbook. Sadly we don't provide previews (yet)!
-  pull_request:
-
-  # Whenever something gets pushed to main, update the docs!
-  # This is great for getting docs changes live without cutting a full release.
-  #
-  # Note that if you're using cargo-dist, this will "race" the Release workflow
-  # that actually builds the Github Release that oranda tries to read (and
-  # this will almost certainly complete first). As a result you will publish
-  # docs for the latest commit but the oranda landing page won't know about
-  # the latest release. The workflow_run trigger below will properly wait for
-  # cargo-dist, and so this half-published state will only last for ~10 minutes.
-  #
-  # If you only want docs to update with releases, disable this one.
-  push:
-    branches:
-      - main
-  
-  # Whenever a workflow called "Release" completes, update the docs!
-  #
-  # If you're using cargo-dist, this is recommended, as it will ensure that
-  # oranda always sees the latest release right when it's available. Note
-  # however that Github's UI is wonky when you use workflow_run, and won't
-  # show this workflow as part of any commit. You have to go to the "actions"
-  # tab for your repo to see this one running (the gh-pages deploy will also
-  # only show up there).
-  workflow_run:
-    workflows: ["Release"]
-    types:
-      - completed
-
-# Alright, let's do it!
-jobs:
-  web:
-    name: Build and deploy site and docs
-    runs-on: ubuntu-latest
-    steps:
-      # Setup
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: swatinem/rust-cache@v2
-
-      # Install and run oranda (and mdbook)
-      # This will write all output to ./public/ (including copying mdbook's output to there)
-      - name: Install and run oranda
-        run: |
-          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/latest/download/oranda-installer.sh | sh
-          oranda build
-
-      # Deploy to our gh-pages branch (making it if it doesn't exist)
-      # the "public" dir that oranda made above will become the root dir
-      # of this branch.
-      #
-      # Note that once the gh-pages branch exists, you must
-      # go into repo's settings > pages and set "deploy from branch: gh-pages"
-      # the other defaults work fine.
-      - name: Deploy to Github Pages
-        uses: JamesIves/github-pages-deploy-action@v4.4.1
-        # ONLY if we're on main (so no PRs or feature branches allowed!)
-        if: ${{ github.ref == 'refs/heads/main' }}
-        with:
-          branch: gh-pages
-          # Gotta tell the action where to find oranda's output
-          folder: public
-          token: ${{ secrets.GITHUB_TOKEN }}
-          single-commit: true
-
-

Elsewhere

-

oranda is, effectively, a static site generator. It outputs HTML, CSS and JavaScript files. These can all be hosted on a -looooot of different platforms, in fact, too many for us to enumerate here! You can use Vercel, Netlify, any GitHub pages -competitor, or you can plop it on your own server that runs nginx, Apache httpd, Caddy, or anything else!

-

You can, in fact, also use the CI example linked above and modify it to deploy to different platforms. If you do, -we'd love to hear about it!

-

Adding static assets

-

If you reference static assets in your Markdown, you'll need to place them all inside a directory at the same level as -your project manifest file called static. This is because Oranda currently doesn't know about each indidivual asset, -and instead just copies the folder where they're contained.

-

In your Markdown, you'll need to refer to the assets in this directory. For example:

-
![An image from my amazing project](./static/project.png)
-
-

If you want to use a custom-named directory you can configure this in your oranda.json, like so:

-
{
-  "build": {
-    "static_dir": "assets"
-  }
-}
-
-

In this case the assets directory will be used instead of the default static directory.

-

Command Line

-

Oranda currently has three subcommands that work in similar, but nuanced ways.

- -

Oranda supports some common options on each command:

-
    -
  • --verbose. This controls the verbosity level for logs.
    • -
  • --output-format. If you want JSON for processing it with a machine, this is where you'd toggle it.
    • -
-

oranda build

-

This command builds your oranda site. You can specify:

-
    -
  • The project root (--project-root), in case you want to build from another directory
    • -
  • The config path (--config-path), if your configuration file is not ./oranda.json
    • -
-

oranda serve

-

This command launches a small axum-powered server that serves your generated oranda site.

-

Importantly, this does not build your site for you. If it can't find a build in the public/ directory, -it will error and exit. You can set the port for the server to be launched using the --port option.

-

oranda dev

-

This command basically combined oranda build and oranda serve, with the added benefit of watching for changes -and recompiling automatically. When you launch, what happens is this:

-
    -
  1. Oranda builds your site (unless you told it not to)
    2. -
  2. Oranda launches a server similar to oranda serve
    3. -
  3. Oranda starts watching its relevant files for changes, and will rerun the build process when something changes
    4. -
-

Oranda's build can have a lot of side-effects (reading/writing files, but also talking to the GitHub API), and as -such, we have to take care to only run the build process when relevant files change. These files are:

-
    -
  • Your project manifest files (Cargo.toml, package.json)
    • -
  • Your oranda configuration file
    • -
  • Any mdbook source files you may have
    • -
  • Your readme, and additional files specified in the configuration
    • -
  • Files immediately relevant to certain components oranda renders (funding, for example)
    • -
  • Any other paths you give it using --include-paths
    • -
-

This command also support several options:

-
    -
  • --port to set a custom port for the file server
    • -
  • --project-root to change the root directory from where your site will be built
    • -
  • --config-path to specify a custom path for your oranda config
    • -
  • --no-first-build to skip the first step mentioned above where oranda builds your site before starting the watch process
    • -
  • -i, --include-paths to specify custom paths for oranda to watch
    • -
-

Tips and Tricks

-

Hiding the Markdown title

-

Oranda breaks out your project's title into its own header, which can be annoying if you've started your own -README.md with something like this:

-
# myprojectname
-
-Blah blah blah etc
-
-

If you build your oranda site like this, the title will appear twice! oranda supports a special class called oranda-hide -that you can wrap your title (or whatever you don't want to appear on the page) with, like this:

-
<div class="oranda-hide">
-
-# myprojectname
-
-</div>
-
-Blah blah blah etc
-
-

Keep in mind the line breaks before and after the HTML, otherwise the Markdown parser may not function correctly.

-

Configuration

- -
-

📦 = automatically collected from your package metadata!

-
-

oranda is designed to work with no configuration- for projects with a -package.json or Cargo.toml, oranda will grab the project metadata it needs -from your project manifest file. It can also infer a lot of the things it wants to -render from your already existing environment.

-

If you project has both a Cargo.toml and a package.json we recommend defining -project metadata fields like name in your oranda.json.

-

Manifest file: oranda.json

-

If you'd like to customize your project you can do so in a oranda.json file.

-

For example:

-
{
-  "build": {
-    "path_prefix": "oranda"
-  },
-  "styles": {
-    "theme": "axodark",
-    "favicon": "https://www.axo.dev/favicon.ico"
-  },
-  "marketing": {
-    "social": {
-      "image": "https://www.axo.dev/meta_small.jpeg",
-      "image_alt": "axo",
-      "twitter_account": "@axodotdev"
-    },
-    "analytics": {
-      "plausible": {
-        "domain": "opensource.axo.dev"
-      }
-    }
-  },
-  "components": {
-    "changelog": true,
-    "artifacts": {
-      "package_managers": {
-        "preferred": {
-          "npm": "npm install @axodotdev/oranda --save-dev",
-          "cargo": "cargo install oranda --locked --profile=dist"
-        },
-        "additional": {
-          "npx": "npx @axodotdev/oranda",
-          "binstall": "cargo binstall oranda",
-          "nix-env": "nix-env -i oranda",
-          "nix flake": "nix profile install github:axodotdev/oranda"
-        }
-      }
-    }
-  }
-}
-
-
-

NOTE: All paths in oranda.json are relative to the oranda.json file.

-
-

Workspace manifest file: oranda-workspace.json

-
-

Added in version 0.3.0.

-
-

oranda supports building multiple sites at once (referred to as building in a "workspace"). To control this behavior, -you can create a oranda-workspace.json file inside your workspace root. Running an oranda command will pick up this -file, and build the workspace members accordingly.

-

The workspace file supports all other oranda config keys, which will be passed down to each workspace members.

-

Read more about workspaces

-

Project Configuration

-

name

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest name field
    • -
-

Your project's name.

-

version

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest version field.
    • -
-

Your project's current version.

-

description

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest description field
    • -
-

Your project's description.

-

homepage

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest homepage field
    • -
-

Your project's homepage.

-

repository

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest repository field
    • -
-

Your project's Git repository.

-

readme_path

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: A variation of the standard README.md
    • -
-

The path to your project's readme file.

-

license

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: Project manifest license field.
    • -
-

Your project's license.

-

Build Configuration

-

dist_dir

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: public/
    • -
-

The directory where your static files will be output to. This must be relative to the oranda.json file.

-

static_dir

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: static/
    • -
-

Static content that oranda will copy to its output folder. This must be relative to the oranda.json file.

-

path_prefix

-
-

Added in version 0.1.0.

-
-

If you're hosting oranda on a nested path (e.g. mysite.cool/myproject), you should set path_prefix to -myproject in your configuration in order for oranda to generate correct links.

-

additional_pages

-
-

Added in version 0.1.0.

-
-

An object of additional Markdown pages that you'd like to be included. All of these will appear in the site header.

-

More information

-

Marketing Configuration

-

analytics

-
-

Added in version 0.1.0.

-
-

Configuration for page analytics.

-

More information

-

social

-
-

Added in version 0.1.0.

-
-

Options useful for SEO features.

-

More information

-

Style Configuration

-

theme

-
-

Added in version 0.1.0.

-
-
    -
  • Default value: dark
    • -
-

Choose which built-in theme to use.

-

More information

-

additional_css

-
-

Added in version 0.1.0.

-
-

Add extra CSS to your pages' header.

-

More information

-

oranda.css_version

-
-

Added in version 0.1.0.

-
-

Specify a version of the embedded oranda CSS. This can be used to opt into newer CSS releases that don't have -an oranda release associated with them yet. (Internally, this looks for a oranda.css release artifact on the given -tag in the axodotdev/oranda GitHub repository)

- -
-

Added in version 0.1.0.

-
-

Path to a custom logo to be shown in your website header.

-

favicon

-
-

Added in version 0.1.0.

-
-

Path to a custom favicon.

-

Components Configuration

-

artifacts

-
-

Added in version 0.1.0.

-
-

Configuration for enabling downloadable artifacts, as well as the cargo-dist integration.

-

More information

-

mdbook or md_book

-
-

Added in version 0.1.0.

-
-

Configuration for mdbook.

-

More information

-

changelog

-
-

Added in version 0.1.0.

-
-

Enable changelog generation.

-

More information

-

funding

-
-

Added in version 0.1.0.

-
-

Allows you to tweak or disable oranda's funding page.

-

More information

-

Configuration before 0.1.0

-

Before version 0.1.0 (the last stable version was/is 0.0.3, the last prerelease was/is 0.1.0-prerelease7), the -configuration format looked like this:

-
{
-  "name": "oranda",
-  "description": "generate static sites for your dev tools",
-  "dist_dir": "oranda_out",
-  "homepage": "https://oranda.axo.dev",
-  "static_dir": "static",
-  "no_header": false,
-  "readme_path": "dev/README.md",
-  "repository": "https://github.com/axodotdev/oranda",
-  "additional_pages": {
-    "Another page": "dev/additional.md"
-  },
-  "favicon": "https://www.axo.dev/favicon.ico",
-  "analytics": {
-    "plausible": {
-      "domain": "tools.axo.dev/oranda"
-    }
-  },
-  "social": {
-    "image": "https://www.axo.dev/meta_small.jpeg",
-    "image_alt": "axo",
-    "twitter_account": "@axodotdev"
-  },
-  "artifacts": {
-    "cargo_dist": true
-  },
-  "logo": "assets/oranda.png",
-  "license": "MIT OR Apache-2.0",
-  "mdbook": false,
-  "path_prefix": "oranda",
-  "styles": {
-    "theme": "axo_dark"
-  },
-  "funding": {
-    "preferred_funding": "github"
-  },
-  "changelog": true
-}
-
-

Artifacts & cargo-dist

-

oranda has first-class support for handling releases generated by cargo-dist. It can even detect the user's platform and recommend the best installer/archive to use!

-

Artifact settings are managed in the artifacts key in your oranda config. This is what an example config looks like:

-
{
-  "components": {
-    "artifacts": {
-      "package_managers": {
-        "preferred": {
-          "npm": "npm install @axodotdev/oranda --save-dev",
-          "crates.io": "cargo install oranda --locked --profile=dist",
-        },
-        "additional": {
-          "npx": "npx @axodotdev/oranda",
-          "binstall": "cargo binstall oranda"
-        }
-      }
-    }
-  }
-}
-
-

Enabling cargo-dist

-

oranda will automatically attempt to find a cargo-dist config in your Cargo.toml. If you want to force disable this, -set components.artifacts.cargo_dist to false. Once oranda determines that cargo-dist support should be enabled, -the following will happen:

-
    -
  • oranda will attempt to find GitHub releases generated by cargo-dist
    • -
  • A new "Install" page will be generated, containing all artifacts and installers for the latest version
    • -
  • A section to quickly install the latest release for the user's current platform will be added to the homepage
    • -
-

Enabling arbitrary GitHub release support

-

Even if you don't have cargo-dist set up, oranda can attempt to glean information about your supported targets and -OSes from your GitHub release artifacts. It will attempt to do this if it can find any releases associated with your -repository. It does this by trying to see if it can recognize any known target triples from your filenames, so for example, -it will recognize mytool-aarch64-apple-darwin.tar.gz. If you would like to completely disable this, set -components.artifacts to false (we may offer a more fine-grained setting for this in the future).

-

Adding package manager installation instructions

-

You can add custom installation instructions for package managers or package manager-esque methods using the -components.artifacts.package_managers key. These are broken up into two sections:

-
    -
  • components.artifacts.package_managers.preferred - methods that you want to be recommended on the front page install -widget
    • -
  • components.artifacts.package_managers.additional - methods that should only show up on the dedicated "install" page
    • -
-

All package manager entries are currently treated as "cross-platform", meaning they'll show up in the install widget for -any platform you support. We're aware of this limitation, and will likely expand support for this in the future.

-

Additional Pages

-

If you have extra Markdown files you'd like to link directly as root pages on your generated website, you can -use the additional_pages option to list them.

-

The option's format is an object with the human-readable page name as keys, and the path to the file as values. Example:

-
{
-  "build": {
-    "additional_pages": {
-      "Another page": "./AnotherFile.md"
-    }
-  }
-}
-
-

Analytics

-

oranda supports automatically inserting the correct analytics snippet your provider into your generated pages.

-

Right now we support the following analytics providers:

- -

To add any of these, add the required configuration under the analytics key:

-

Google Analytics

-
{
-  "marketing": {
-    "analytics": {
-      "google_analytics": {
-        "tracking_id": "String"
-      }
-    }
-  }
-}
-
-

Plausible

-
{
-  "marketing": {
-    "analytics": {
-      "plausible": {
-        "domain": "String",
-        "script_url": "Optional string for self hosted"
-      }
-    }
-  }
-}
-
-

Fathom

-
{
-  "marketing": {
-    "analytics": {
-      "fathom": {
-        "site": "String"
-      }
-    }
-  }
-}
-
-

Unami

-
{
-  "marketing": {
-    "analytics": {
-      "unami": {
-        "website": "String",
-        "script_url": "String"
-      }
-    }
-  }
-}
-
-

Changelogs

-

oranda supports reading your project's changelogs from GitHub releases. You can enable this by setting components.changelog to true:

-
{
-  "components": {
-    "changelog": true
-  }
-}
-
-

This will result in a new "Changelog" page being generated. Changelogs are pulled directly from GitHub releases. If -you're using the cargo-dist integration, oranda will attempt to parse a CHANGELOG.md-like file for -the changelogs instead.

-
-

NOTE: We're working on getting changelog parsing from a CHANGELOG.md file as a default feature, without requiring -use of cargo-dist!

-
-

mdbook support

-

oranda can generate mdbooks for you. If you've already worked with mdbook, it's as simple as pointing oranda -at your book directory using the mdbook.path option:

-
{
-  "components": {
-    "mdbook": {
-      "path": "./docs"
-    }
-  }
-}
-
-

This will cause oranda to automatically recompile your book for you, which will be served at the yoursite/book/ URL. -oranda dev will also be watching this directory.

-

mdbook quickstart

-

If this is the first time you're working with mdbook, these are the minimal steps you'd need before editing the oranda config. -After you've installed the mdbook tool, you can generate a new book scaffold:

-
mdbook init docs # replace docs with your preferred directory
-
-

You can either use oranda dev or mdbook serve docs/ to have a preview for your mdbook.

-

Social

-

In order to help with SEO, there are a couple of options you can use.

-
{
-  "marketing": {
-    "social": {
-      "image": "used as the share image for social media",
-      "image_alt": "alt for said image",
-      "twitter_account": "twitter account for the website"
-    }
-  }
-}
-
-

Theming

-

Predefined themes

-

Oranda comes with six default themes:

-
    -
  • Light
    • -
  • Dark
    • -
  • Axo Light (axo_light or axolight)
    • -
  • Axo Dark (axo_dark or axodark)
    • -
  • Hacker
    • -
  • Cupcake
    • -
-

You can change the theme by adding the styles.theme key to your oranda.json:

-
{
-  "styles": {
-    "theme": "hacker"
-  }
-}
-
-

Dark is the default theme.

-

Customizing Themes

-

Themes can be further customized by adding extra CSS.

-

Additional CSS can be added using the styles.additional_css key.

-
{
-  "styles": {
-    "additional_css": ["./local/file.css", "http://www.remote.dev/file.css"]
-  }
-}
-
-
-

Note: Remote files will be copied and the copy served locally, so once a link is updated, the site must be regenerated for changes to take effect.

-
-

Adding CSS

-

Oranda's CSS makes use of cascade layers to scope CSS and make it simpler to override styles. To override themed styles, say on a <p> element, place it inside a layer called overrides.

-
@layer overrides {
-  p {
-    color: aquamarine;
-  }
-}
-
-

Alternately, CSS that is not defined within a layer has precedence over all layered CSS, so this will also work.

-
p {
-  color: aquamarine;
-}
-
-

Dark vs. Light

-

When the dark theme is selected, a dark class is added to the page, and styles to be applied in dark mode only can include this selector. For instance,

-
.dark p {
-  color: aquamarine;
-}
-
-

Will create paragraphs colored aquamarine in dark mode only.

-

Adding Classes

-

When there are specific elements you would like to add to your pages, these can be added into Markdown files as raw HTML with class selectors that you can target with your CSS.

-
<!-- README.md -->
-
-## A Different Kind of Box
-
-<div class="my-border-class">
-  <p>An outlined box</p>
-</div>
-
-
.my-border-class {
-  padding: 1rem;
-  border: 6px dotted seagreen;
-}
-
-

Creating a New Theme

-

Currently, to create a new theme, you need to follow the directions above in "Customizing Themes" and overwrite the given CSS. We recommend continuing the layer approach and placing overrides in the overrides layer and then adding a new named layer for your theme.

-

The ability to add a different theme directly will be included in future releases. Following the layers approach will make it simpler to transition your theme.

-

Theme Previews

-

Here you can see what themes look like without having to set up oranda yourself.

-

These previews are generated by running oranda on itself.

-

Dark (default)

-

dark theme preview

-

Light

-

light theme preview

-

Axo Dark

-

axo dark theme preview

-

Axo Light

-

axo light theme preview

-

Hacker

-

hacker theme preview

-

Cupcake

-

cupcake preview

-

Funding page

-

Oranda has the capability of reading information from your GitHub funding file, and -automatically writing a page based on it. Unless you disable it by setting components.funding to false -in the oranda config file, oranda will search your project for -a .github/FUNDING.yml file, and generate a page based off of it. You can read -more about the format of this file on GitHub's docs.

-

Oranda will display your different sponsor/funding links next to each other, but -if you have a "main" funding option, you can set the following configuration setting:

-
{
-  "components": {
-    "funding": {
-      "preferred_funding": "github"
-    }
-  }
-}
-
-

Make sure this key corresponds to one of the possible entries in the FUNDING.yml -file.

-

If you want to display additional information or context, oranda can also include -the contents of a top-level funding.md Markdown file. Its contents will be translated -into HTML and displayed on the Funding page as well.

-

Both of the YAML and Markdown file paths can be customized as such:

-
{
-  "components": {
-    "funding": {
-      "md_path": "myfunding.md",
-      "yml_path": "misc/funding.yml"
-    }
-  }
-}
-
-
-

oranda's funding parsing and site generation are currently an experiment into how -to better integrate common funding methods into your tools' websites. If you have -any feedback on how we could do things better, let us know on -Discord or GitHub!

-
-

Workspaces

-

oranda supports building multiple sites at once (referred to as building in a "workspace"). To control this behavior, -you can create a oranda-workspace.json file inside your workspace root. Running an oranda command will pick up this -file, and build the workspace members accordingly.

-

The reason why this is a separate file, and not part of the oranda.json file is to avoid confusing between nonvirtual -workspace root members (meaning if a workspace root also contains a site/package of some kind). By putting your workspace -configuration in a separate file, you can still have an oranda site at the same directory level, without any problems.

-
-

NOTE: Workspace functionality will not be enabled if the oranda-workspace.json file doesn't exist!

-
-

A workspace configuration file looks something like this:

-
{
-  "workspace": {
-    "name": "My Workspace",
-    "members": [
-      {
-        "slug": "projectone",
-        "path": "./project-one"
-      },
-      {
-        "slug": "project_two",
-        "path": "./project-two"
-      }
-    ]
-  }
-}
-
-

When ran with oranda build, this will produce two oranda sites, one at /projectone, and one at /project_two. oranda -will consider each separate project's oranda.json file (should it exist).

-

You can additionally pass down keys you'd like to be set for each member project:

-
{
-  "workspace": {
-    // same as above
-  },
-  "styles": {
-    "theme": "hacker" // set every site's theme to hacker
-  }
-}
-
-

Individual workspace member configs will still override what's set here, though. Also, every key will be passed down, -including ones that don't make a lot of sense to be the same in multiple projects (for example package manager -configuration).

-

Building a workspace will also generate a nice workspace index page that can be used to provide an overview over the -workspace's members, as well as some quick info and metadata.

-

List of workspace configuration keys

-
    -
  • name - set the overarching workspace name
    • -
  • auto - enable workspace autodetection
    • -
  • generate_index - disable generating a workspace index page
    • -
  • members - list the workspace members - -
    • -
-

name

-
-

Added in version 0.3.0.

-
-

Set the overarching workspace name. This is optional, and will fall back to "My Oranda Workspace" if not set (not very -intuitive, I know).

-

auto

-
-

Added in version 0.3.0.

-
-

Enables workspace autodetection if set to true. This will cause oranda to attempt to find any Cargo or NPM workspaces -under the current directory, and to attempt to build all of its members (all members must therefore have at least a -readme file). Members manually listed under the members key override these automatically detected workspace members.

-

generate_index

-
-

Added in version 0.3.0.

-
-

If set to false, does not generate a workspace index page that links between all workspace members. Use this if you -just want to use oranda's workspace functionality to build multiple unrelated sites in one go.

-

members

-
-

Added in version 0.3.0.

-
-

An array of objects representing the workspace members.

-

members.slug

-
-

Added in version 0.3.0.

-
-

The URL-safe slug this page will be built at. This needs to be something that can be parsed as a URL, as well as a folder -name on your target system (because oranda is a static site generator, after all).

-

members.path

-
-

Added in version 0.3.0.

-
-

The path to the page source. Point this to the same directory that the oranda.json would be in.

-

Contributing

-

Here's some helpful tips for contributing.

-

Auto-recompiling based on source changes

-

If you're working on oranda and you want to rebuild both oranda itself and your preview site when stuff changes, -this is the command to keep in mind (assuming you have cargo-watch installed):

-
cargo watch -x "run dev"
-
-

On some platforms, apparently images also get recompiled and picked up by cargo-watch:

-
cargo watch -x "run dev" --ignore "*.png"  --ignore "*.jpg"
-
-

...plus working on the CSS

-

As long as you're working with a development build of oranda (by running cargo run without the --release flag), -oranda will automatically download a version of the Tailwind compiler and compile the CSS from your -local checkout for you.

-

oranda dev doesn't automatically reload on CSS changes (because it's meant to be used by users), -but you can include the CSS directory manually like such:

-
cargo run dev -i oranda.css/css/
-
-

Updating syntax highlighting languages

-

We use syntect to support syntax highlighting in Markdown code blocks. If you want to add support for a new language -that's not included in syntect's default set of languages or the ones oranda provides, you'll need to extend the -oranda::site::markdown::syntax_highlight::dump_syntax_themes function to load your new .sublime-syntax file from disk -and to include it in our syntax set dump. This function, once adjusted, only needs to be ran once manually, by including -it anywhere in the call path of the application (I recommend somewhere close to the top of the build CLI function).

-

Converting from .tmLanguage

-

syntect accepts .sublime-syntax files, but Sublime Text can also accept .tmLanguage (TextMate syntax bundles) files, -so sometimes we need to convert from one to the other. Thankfully, the Sublime Text editor has a built-in feature for this. -Here's what you need to do:

-
    -
  1. Download and install Sublime Text
    2. -
  2. In Sublime Text, from the menu, select Tools -> Developer -> New Syntax...
    3. -
  3. This puts you in your Packages/User folder. Paste your tmLanguage file contents and save as <yourlang>.tmLanguage.
    4. -
  4. Next, you should be able to run Tools -> Developer -> New Syntax from .tmLanguage...
    5. -
  5. This opens a new tab with the converted output. Save and copy it or paste it into a new file in oranda. Profit!
    6. -
- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - - -
- - - -================ public/book/quickstart.html ================ - - - - - - Quickstart - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Quickstart

-

After you've installed oranda, it's time to give it a spin. Make sure you can execute the -oranda command, its output should look something like this:

-
$ oranda
-🎁 generate beautiful landing pages for your projects
-
-Usage: oranda [OPTIONS] <COMMAND>
-
-Commands:
-build
-dev
-serve
-help Print this message or the help of the given subcommand(s)
-
-Options:
--h, --help Print help (see more with '--help')
--V, --version Print version
-
-GLOBAL OPTIONS:
---verbose <VERBOSE> How verbose logging should be (log level) [default: warn] [possible values:
-off, error, warn, info, debug, trace]
---output-format <OUTPUT_FORMAT> The format of the output [default: human] [possible values: human, json]
-
-
-

Basic Setup

-

oranda is designed to be a tool you can simply drop into an existing project. For the purposes of this -guide, we're going to use minimal-axolotlsay, a simple CLI project, but you can use one of your own -projects, or even set up a new one from scratch! The only hard requirement oranda has is for your -project to have a readme file (README.md).

-

The easiest way to get a feedback loop going with oranda is to move into the directory and run oranda dev:

-
git clone https://github.com/axodotdev/minimal-axolotlsay
-cd minimal-axolotlsay
-oranda dev
-
-

oranda dev is a command that will automatically recompile your oranda build when you change -one of the files relevant to it. It also launches a file server that'll allow you to look at the output - -if you open localhost:7979, you'll see something like this:

-

an image of the default oranda output when ran on axolotlsay

-

oranda has picked up on our readme file and converted it into a static page! How nice!

-

minimal-axolotlsay also has integration with cargo-dist already set up - a powerful way to streamline -cross-platform releases of applications. Since oranda and cargo-dist integrate, oranda already knows -about our cargo-dist releases, and automatically shows a widget and page to download the latest binaries.

-

How does oranda know where our repository is? It extracts the repository key from our Cargo.toml file! -oranda can do this for Rust and JavaScript/Node.js-based projects at the moment. This way, you don't need to -explicitly specify a lot of info you may already be keeping elsewhere.

-

Beyond the Basics

-

If we want to work with the more advanced features that oranda offers, we'll have to create a configuration file. -The default location of this file is oranda.json in the same directory where your project manifest is located. -You can view a full reference of the configuration schema here. Let's start by making the simplest and highest impact change: telling oranda that our project has changelogs that it should make pages for!

-
{
-  "components": {
-    "changelog": true
-  }
-}
-
-

If you now build again (you may have to restart oranda dev since we added a new file to watch), it should look like this:

-

an image of oranda with changelogs enabled

-

oranda pulled our project's releases from GitHub automatically, without us having to specify any further configuration -than enabling the changelog setting!

-

Further Steps

-

For more specific configuration, check out the configuration page and its sub-pages.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - -================ public/book/tips.html ================ - - - - - - Tips and Tricks - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - -
- -
- - - - - - - - -
-
-

Tips and Tricks

-

Hiding the Markdown title

-

Oranda breaks out your project's title into its own header, which can be annoying if you've started your own -README.md with something like this:

-
# myprojectname
-
-Blah blah blah etc
-
-

If you build your oranda site like this, the title will appear twice! oranda supports a special class called oranda-hide -that you can wrap your title (or whatever you don't want to appear on the page) with, like this:

-
<div class="oranda-hide">
-
-# myprojectname
-
-</div>
-
-Blah blah blah etc
-
-

Keep in mind the line breaks before and after the HTML, otherwise the Markdown parser may not function correctly.

- -
- - -
-
- - - -
- - - - - - - - - - - - - - - - - - -
- - - ================ public/changelog/css-v0.0.0/index.html ================