docs	install	build

Build statically-hostable, interactive HTML forms for making web requests

Powered by react-json-schema-form and react-bootstrap.

Visitors to a urljsf-built page see:

• one or more interactive HTML forms...
  • defined by and validated against a JSON Schema, optionally with...
  • deep customizable user interface
  • pre-filled data
  • custom validation checks

Once the data is validated, the user sees a button which gets a URL, which can be:

• downloaded as a file
• opened in a new browser window
• copy and pasted
• submitted to an HTTP endpoint, either by opening a new window, or directly.
• open native applications like email

urljsf doesn't ship a server, so that part is up to you!

Site builders write TOML, JSON, YAML or python, then can use urljsf as:

• a drop-in-and-pray script
• a standalone CLI tool
• a sphinx or mkdocs extension

... to create JavaScript/HTML forms that helps visitors provide good data for:

• pull requests
• issues
• galleries
• surveys
• on-demand build services
• precise test descriptions
• linter rules

urljsf is distributed on PyPI, with several optional extras to help ensure tested versions are available:

pip install urljsf
# ... or    urljsf[sphinx]   for sphinx
# ... or    urljsf[mkdocs]   for mkdocs and pymdown-extensions
# ... or    urljsf[yaml]     for build time YAML parsing

# or...
uv install urljsf
# etc.

urljsf is also distributed on conda-forge, with similar extras:

pixi add urljsf
# ... or urljsf-with-sphinx
# ... or urljsf-with-mkdocs
# ... or urljsf-with-yaml

# or...
micromamba install -c conda-forge urljsf
# or...
mamba install -c conda-forge urljsf
# or...
conda install -c conda-forge urljsf
# etc.

See the contributing guide for a development install.

urljsf work with some JSON schema constrained files as a:

• (not-recommended) hot-linked script
• a standalone site generator for simple sites
• a plugin for the sphinx and mkdocs documentation systems

A urljsf is built from a number of JSON schema-constrained files. Writing these in plain JSON is tedious, so TOML and YAML are also supported inputs for any of the methods below. Learn more on the schema documentation.

A very simple, but limited, usage is an .html file that links to urljsf and bootstrap resources on the internet.

<script type="application/vnd.deathbeds.urljsf.v0+toml">
  [forms.url.schema]
  title = "pick an xkcd"
  description = "this will redirect to `xkcd.com`"
  type = "object"
  required = ["xkcd"]
  properties.xkcd = {type="integer", minimum=1, maximum=2997}

  [forms.url.ui_schema.xkcd."ui:options"]
  widget = "range"

  [templates]
  url = "https://xkcd.com/{{ data.url.xkcd }}"
  submit_button = "see xkcd #{{ data.url.xkcd }}"
</script>
<script
  type="module"
  src="https://deathbeds.github.io/urljsf/_static/index.js"
></script>

This technique has many limitations, and is not recommended.

Some ways to improve:

• download a GitHub release and unpack it, serving the files next to it
• ensure bootstrap is loaded before the script, with a link tag in a head.
• on the script element, use a src to point to a valid urljsf definition
• use the CLI or a documentation extension for sphinx or mkdocs

The urljsf command line generates a ready-to-serve, standalone site with all required static assets. Written in python, it can reuse the extensive JSON schema support in the python ecosystem, such as msgspec or pydantic.

prsf --help

urljsf requires at least a definition file, but offers many command line options: see the documentation for more.

After installing with the [sphinx] extra, add urljsf.sphinxext to conf.py:

# conf.py
extensions = [
  # ... other extensions
  "urljsf.sphinxext",
]

Then use the urljsf directive in source files:

.. urljsf:  # a relative path to a description as a TOML, YAML, or JSON file or python
  :toml:
  # a form definition in TOML

See the documentation for more about configuring urljsf.sphinxext, the urljsf directive, and more advanced use cases.

After installing with the [mkdocs] extra, add urljsf to mkdocs.yml:

# mkdocs.yml
plugins:
  - urljsf

Then use the urljsf fenced code block in source files:

```urljsf {path=path/to/defnition.toml}

```

See the documentation for more about configuring urljsf, the urljsf fence, and more advanced use cases.

• react-json-schema-form cannot represent all possible data structures, such as writing a new JSON schema in JSON schema, or many features added after Draft 7
• the generated scripts won't work when served from file:// due to browser CORS headers requirements for type="module" scripts
• the sphinx integration is only tested with the html builder, the basic alabaster theme, and pydata-sphinx-theme (by way of urljsf's own documentation)
• the mkdocs integration is only tested with the default theme

urljsf itself is licensed under the BSD-3-Clause license. You can do whatever you want with it, but if you change it a lot, it's not the maintainers' problem.

urljsf distributes third-party JavaScript and CSS in various forms, licensed under the MIT, BSD-3-Clause, and ISC licenses.