web.docusaurus #

Docusaurus Module with HeroLib

This module allows you to build and manage Docusaurus websites using a generic configuration layer provided by lib/web/site.

Workflow

1. Configure Your Site: Define your site's metadata, navigation, footer, pages, and content sources using !!site.* actions in a .heroscript file. This creates a generic site definition.
2. Define Docusaurus Build: Use !!docusaurus.define to specify build paths and other factory-level settings.
3. Link Site to Docusaurus: Use !!docusaurus.add to link your generic site configuration to the Docusaurus factory. This tells HeroLib to build this specific site using Docusaurus.
4. Run Actions: Use actions like !!docusaurus.dev or !!docusaurus.build to generate and serve your site.

Hero Command (Recommended)

For quick setup and development, use the hero command:

##hero docs -d -path /path/to/your/site

##hero docs -b -path /path/to/your/site

##hero docs -bp -path /path/to/your/site

Example HeroScript

// Define the Docusaurus build environment, is optional
!!docusaurus.define
    path_build: '/tmp/docusaurus_build'
    path_publish: '/tmp/docusaurus_publish'
    reset: 1
    install: 1
    template_update: 1

!!docusaurus.add
    sitename:'my_site'
    path:'./path/to/my/site/source'
    path_publish: '/tmp/docusaurus_publish'                                                 //optional
    git_url:'https://git.threefold.info/tfgrid/docs_tfgrid4/src/branch/main/ebooks/tech'    //optional: can use git to pull the site source
    git_root:'/tmp/code'                                                                    //optional: where to clone git repo
    git_reset:1                                                                             //optional: reset git repo
    git_pull:1                                                                              //optional: pull latest changes
    play:true                                                                               //required when using git_url: process heroscript files from source path


// Run the development server
!!docusaurus.dev site:'my_site' open:true watch_changes:true

see sites to define a site

the site needs to be defined following the generic site definition, see the lib/web/site module for more details.

//Configure the site using the generic 'site' module
!!site.config
    name: 'my_site'
    title: 'My Awesome Docs'
    tagline: 'The best docs ever'
    url: 'https://docs.example.com'
    base_url: '/'
    copyright: 'Example Corp'

!!site.menu_item
    label: 'Homepage'
    href: 'https://example.com'
    position: 'right'

// ... add footer, pages, etc. using !!site.* actions ...

Heroscript Actions

• !!docusaurus.define: Configures a Docusaurus factory instance.

• name (string): Name of the factory (default: default).

• path_build (string): Path to build the site.

• path_publish (string): Path to publish the final build.

• reset (bool): If true, clean the build directory before starting.

• template_update (bool): If true, update the Docusaurus template.

• install (bool): If true, run bun install.

• !!docusaurus.add: Links a configured site to the Docusaurus factory.

• site (string, required): The name of the site defined in !!site.config.

• path (string, required): The local filesystem path to the site's source directory (e.g., for static/ folder).

• !!docusaurus.dev: Runs the Docusaurus development server.

• site (string, required): The name of the site to run.

• host (string): Host to bind to (default: localhost).

• port (int): Port to use (default: 3000).

• open (bool): Open the site in a browser.

• watch_changes (bool): Watch for source file changes and auto-reload.

• !!docusaurus.build: Builds the static site for production.

• site (string, required): The name of the site to build.

fn config() !DocusaurusConfig

return the last know config

fn config_set(args_ DocusaurusConfigParams) !

fn dsite_define(sitename string) !

fn dsite_exists(name_ string) !bool

fn dsite_get(name_ string) !&DocSite

fn dsite_names() []string

dsite_names returns the list of defined docusaurus site names.

fn play(mut plbook PlayBook) !

enum ErrorCat {
	unknown
	image_double
	file_double
	file_not_found
	image_not_found
	page_double
	page_not_found
	sidebar
	circular_import
	def
	summary
	include
}

struct AddArgs {
pub mut:
	sitename string // needs to exist in web.site module
}

struct AnnouncementBar {
pub mut:
	id               string @[json: 'id']
	content          string @[json: 'content']
	background_color string @[json: 'backgroundColor']
	text_color       string @[json: 'textColor']
	is_closeable     bool   @[json: 'isCloseable']
}

struct Configuration {
pub mut:
	main         Main
	navbar       Navbar
	footer       Footer
	announcement AnnouncementBar
}

IS THE ONE AS USED BY DOCUSAURUS

struct DevArgs {
pub mut:
	host          string = 'localhost'
	port          int    = 3000
	open          bool   = true  // whether to open the browser automatically
	watch_changes bool   = false // whether to watch for changes in docs and rebuild automatically
}

struct DocSite {
pub mut:
	name string
	url  string
	// path_src     pathlib.Path
	path_publish pathlib.Path
	path_build   pathlib.Path
	errors       []SiteError
	config       Configuration
	website      site.Site
	generated    bool
}

fn (mut s DocSite) build() !

fn (mut s DocSite) build_dev_publish() !

fn (mut s DocSite) build_publish() !

fn (mut s DocSite) dev(args DevArgs) !

fn (mut s DocSite) error(args ErrorArgs)

fn (mut docsite DocSite) generate() !

fn (mut docsite DocSite) generate_docs() !

Generate docs from site configuration

fn (mut docsite DocSite) import() !

fn (mut s DocSite) open(args DevArgs) !

fn (mut docsite DocSite) store_site_structure() !

Store the Docusaurus site structure in Redis for link processing This maps collection:page to their actual Docusaurus paths

struct DocusaurusConfig {
pub mut:
	path_build      pathlib.Path
	path_publish    pathlib.Path
	install         bool
	reset           bool
	template_update bool
	coderoot        string
}

struct DocusaurusConfigParams {
pub mut:
	path_build      string
	path_publish    string
	install         bool
	reset           bool
	template_update bool
	coderoot        string
}

struct ErrorArgs {
pub mut:
	path string
	msg  string
	cat  ErrorCat
}

struct Footer {
pub mut:
	style string
	links []FooterLink
}

struct FooterItem {
pub mut:
	label string
	href  string @[omitempty]
	to    string @[omitempty]
}

struct FooterLink {
pub mut:
	title string
	items []FooterItem
}

struct Logo {
pub mut:
	alt      string
	src      string
	src_dark string @[json: 'srcDark']
}

struct Main {
pub mut:
	title          string
	tagline        string
	favicon        string
	url            string
	base_url       string @[json: 'baseUrl']
	url_home       string
	image          string
	metadata       Metadata
	build_dest     []string @[json: 'buildDest']
	build_dest_dev []string @[json: 'buildDestDev']
	copyright      string
	name           string
}

struct Metadata {
pub mut:
	description string
	image       string
	title       string
}

struct Navbar {
pub mut:
	title string
	logo  Logo
	items []NavbarItem
}

struct NavbarItem {
pub mut:
	label    string
	href     string @[omitempty]
	position string
	to       string @[omitempty]
}

struct SiteError {
	Error
pub mut:
	path string
	msg  string
	cat  ErrorCat
}