contentcode

package
v0.5.39 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: BSD-3-Clause Imports: 25 Imported by: 0

Documentation

Overview

Package contentcode compiles the runnable Go and Goal code blocks (```Go, ```Goal) of the markdown files of a content app into the app: it writes a Go file to the app's package that defines a function for each code block and registers it in cogentcore.org/core/content.CompiledCode (Goal: cogentcore.org/core/content.CompiledGoal). Content then runs those code blocks directly, without an interpreter such as mvm: natively as Go, and in `core build js` apps as the GoScript output of the same code.

Code blocks are written as the interpreter (mvmcore) runs them: a list of statements that use the parent widget b and the packages of the mvmcore symbols (core, styles, ...) without importing them, or a program with a main function. Code blocks that do not type check are left out (and listed in the output file), and their errors are printed at their lines in the markdown files; an unused variable is used with `_ = x` instead, since mvm allows it.

Goal code blocks (```Goal) are compiled per page, in order, so that a block sees the variables of the blocks before it on its page, as in the Goal interpreter (see goal.go and cogentcore.org/core/content.GoalPage). That needs Cogent Lab's Goal transpiler, so the app's module must require cogentcore.org/lab (otherwise, the Goal code blocks are not compiled, with a message that says so); Goal code can use the packages of Lab's mvmlab symbols without importing them.

The core tool runs Generate for every content app (see App) in `core build`, `core run`, `core install`, `core pack` and `core generate`. The contentcode command (cogentcore.org/core/content/cmd/contentcode) runs it from a go:generate directive. The output records a hash of what it is generated from (the code blocks, the options and the go.mod file of the app), and Generate does nothing if that has not changed.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Generate

func Generate(c *Config) (bool, error)

Generate writes the output file of the code blocks of the content, unless it is up to date. It returns whether it wrote the file. If the content has no code blocks, it removes a previously generated output file instead.

Types

type Config

type Config struct {

	// Dir is the directory of the package (default: the current directory).
	// Content and Output are relative to it.
	Dir string

	// Content is the directory of the markdown content.
	Content string

	// Output is the output Go file, in the package.
	Output string

	// Tags are build tags for type checking.
	Tags string

	// Imports are extra packages that code can use: path or name=path.
	Imports []string

	// GoalRecord is whether Goal math mode records its variables in
	// tensorfs and lists tensorfs to the output, as the Goal interpreter
	// of Lab's mvmlab does. It is true by default; set it to false for
	// sites whose interpreter does not (such as plain goal).
	GoalRecord bool

	// Interpret are the pages whose code blocks are not compiled into the
	// app, so that they run in the interpreter, as markdown file paths in
	// the content directory, with or without the .md extension, which can
	// have the wildcards of [path.Match], such as neuron-*. On the web, an
	// interpreter that is a deferred function is then loaded with the
	// packages that the code uses only when such a page is shown, which
	// keeps code that few pages use out of the startup of the app.
	Interpret []string

	// Force generates the output even if it is up to date.
	Force bool
}

Config is the configuration of Generate.

func App

func App(dir string) (*Config, error)

App returns the configuration for the package in dir if it is a content app: a main package that imports the content package and embeds (or has) a directory with markdown files. If a go:generate directive of the package runs contentcode, App uses its arguments. It returns nil if the package is not a content app.

func ParseArgs

func ParseArgs(name string, args []string) (*Config, error)

ParseArgs returns the configuration given by the arguments of the contentcode command.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL