The newdoc tool generates pre-populated module and assembly files formatted with AsciiDoc, which are used in Red Hat and Fedora documentation. The generated files follow the Modular Documentation guidelines: https://redhat-documentation.github.io/modular-docs/.

1. Installing newdoc

You can install newdoc on various operating systems using several package managers.

Fedora, RHEL, and CentOS

To install newdoc on current Fedora, RHEL 8 or later, or CentOS 8 or later, enable the Copr package repository:

  1. Enable the repository:

    # dnf copr enable mmuehlfeldrh/newdoc-rs

  2. Install newdoc:

    # dnf install newdoc

    The Copr repository distributes packages only for supported releases of Fedora. If you have enabled the repository but the package fails to install, check if your Fedora is still supported.

openSUSE Tumbleweed

To install newdoc on openSUSE Tumbleweed:

  1. Enable the Copr package repository:

    # zypper addrepo \
         'https://copr.fedorainfracloud.org/coprs/mmuehlfeldrh/newdoc-rs/repo/opensuse-tumbleweed/mmuehlfeldrh-newdoc-rs-opensuse-tumbleweed.repo'

  2. Install newdoc:

    # zypper refresh
# zypper install --allow-vendor-change newdoc
macOS

To install newdoc on macOS, use the Homebrew package manager:

  1. Install the Homebrew package manager as described on https://brew.sh/.

  2. Add the tap (repository):

    $ brew tap redhat-documentation/repo

  3. Install newdoc:

    $ brew install newdoc
Container

To install newdoc as a container, use Docker or Podman.

Warning

The newdoc container needs to access files in your host file system. It mounts your current directory into the container.

When the container runs, it relabels the SELinux configuration on all files in your current directory. This is necessary in order for the SELinux permissions system to enable file access on Fedora, RHEL, and CentOS.

As a consequence, you cannot run the newdoc container in certain directories specially protected by SELinux, such as at the root of your home directory.

On Fedora, RHEL, and CentOS, replace docker with podman in the following commands:

  1. Download the image:

    $ docker pull quay.io/redhat-documentation/newdoc

  2. Configure a command alias. Save this line in your shell configuration file, such as in the ~/.bashrc file:

    alias newdoc="docker run -it -v .:/mnt/newdoc:Z redhat-documentation/newdoc newdoc"

  3. Open a new terminal to reload the shell configuration.

  4. Test that newdoc works in a documentation directory:

    documentation-directory]$ newdoc
Note
 The default newdoc container is based on the Alpine distribution. If you need to install packages from the RHEL ecosystem in the newdoc container, you can use the quay.io/redhat-documentation/newdoc:distro container variant. It is built on the RHEL 9 UBI Minimal base, and contains the microdnf package manager.
From source on any platform

To install newdoc from source on a Linux distribution, on macOS, or on Microsoft Windows, use the cargo package manager:

  1. Install the Rust toolchain: see https://rustup.rs/.

  2. Install newdoc:

    $ cargo install newdoc

  3. The cargo install command installs newdoc in the ~/.cargo/bin/ directory. To run newdoc without entering the path to the utility, add the ~/.cargo/bin/ directory to your $PATH variable:

    1. Append the following command to your ~/.bashrc file:

      export PATH=$PATH:$HOME/.cargo/bin/"

    2. Reload the settings from ~/.bashrc:

      $ source ~/.bashrc
Verification

  • Test that newdoc works:

    $ newdoc

2. Updating newdoc

You can update newdoc with the package manager that you used to install it.

Fedora, RHEL, and CentOS

To update newdoc that is installed from RPM on Fedora, RHEL, or CentOS, use the DNF package manager:

  1. Make sure that you are using a supported release of your Linux distribution. The Copr repository does not publish newdoc packages for unsupported distribution releases.

  2. Refresh repository metadata and update the package:

    # dnf --refresh upgrade newdoc
openSUSE

To update newdoc installed on openSUSE:

  1. Make sure that you are using a supported release of your Linux distribution. The Copr repository does not publish newdoc packages for unsupported distribution releases.

  2. Refresh repository metadata:

    # zypper refresh

  3. Update the package:

    # zypper update newdoc
macOS

To update newdoc installed on macOS using Homebrew:

  1. Update the repository metadata:

    $ brew update

  2. Update newdoc:

    $ brew upgrade newdoc
Container

To update the newdoc container, use Docker or Podman.

On Fedora, RHEL, and CentOS, replace docker with podman in the following command:

$ docker pull quay.io/redhat-documentation/newdoc
From source on any platform

To update newdoc from source, use the cargo package manager:

  1. Update the Rust toolchain:

    $ rustup update

  2. Update newdoc:

    $ cargo install newdoc

3. Generating documentation files

You can generate a documentation file outline that conforms to the modular templates.

3.1. Creating a new module

  1. In the directory where modules are located, use newdoc to create a new file:

    modules-dir]$ newdoc --procedure "Setting up thing"

    The tool also accepts the --concept and --reference options. You can use these short forms instead: -p, -c, and -r.

  2. Rewrite the placeholders in the generated file with your docs.

3.2. Creating a new assembly

  1. In the directory where assemblies are located, use newdoc to create a new file:

    assemblies-dir]$ newdoc --assembly "Achieving thing"

    You can use the short form of the --assembly option instead:

    assemblies-dir]$ newdoc -a "Achieving thing"

  2. Rewrite the placeholders in the generated file with your docs.

    Add AsciiDoc include statements to include modules. See Include Files in the AsciiDoc Syntax Quick Reference.

    Alternatively, you can use the --include-in option when creating the assembly to generate modules and include them automatically, in a single step. See the description in the Options section.

3.3. Creating a new snippet file

  1. In the directory where snippets are located, use newdoc to create a new file:

    snippets-dir]$ newdoc --snippet "A reusable note"

    You can use the short forms instead:

    snippets-dir]$ newdoc -s "A reusable note"`

  2. Rewrite the placeholders in the generated file with your docs.

3.4. Overwriting existing files

When generating a new file, newdoc warns you if a file by that name already exists in this directory. It prompts you to choose an action.

Procedure

  • To overwrite the existing file with the new file, type yes.

  • To preserve the existing file and cancel the newly generated file, type no.

4. Options

You can use several options on the command line to adjust the newdoc behavior.

Command-line options

  • To generate the file with explanatory comments, add the --comments or -M option when creating documents.

  • To generate the file without the example, placeholder content, add the --no-examples or -E option when creating documents.

  • To generate the file without the metadata attributes header, add the --no-metadata or -D option when creating documents.

  • By default, the content type prefix appears in the generated file name and not in the ID (anchor). To change this behavior, use the following options:

    --no-file-prefixes or -P

    Disables the file-name prefix.

    --anchor-prefixes or -A

    Enables the ID (anchor) prefix.

  • To specify the directory where newdoc saves the generated file, add the --target-dir=<directory> or -T <directory> option.

  • To generate an assembly with include statements for other generated modules, use the --include-in or -i option:

    $ newdoc --include-in "An assembly for two modules" \
         --concept "First module" \
         --procedure "Second module"

    This creates the two modules and an assembly that features the include statements for the modules.

5. Configuration files

You can store newdoc configuration in several configuration files. These adjust the same behavior that you can also set using command-line options.

The configuration files and arguments take the following precedence, from most important (overriding) to least important (overriden):

  1. The command-line arguments.

  2. A .newdoc.toml file in the Git repository where you generate the file.

    If the Git repository is nested, newdoc looks for a configuration file in each repository, and the inner repository takes precedence over the outer one.

  3. A newdoc.toml file in your home directory, depending on your operating system:

    Linux

    ~/.config/newdoc/newdoc.toml

    macOS

    /Users/You/Library/Application Support/com.Red-Hat.newdoc/newdoc.toml

    Windows

    C:\Users\You\AppData\Roaming\Red Hat\newdoc\config\newdoc.toml

The configuration file has the following syntax:

# These are the default values as of newdoc 2.18:
comments = false
examples = true
metadata = true
file_prefixes = true
anchor_prefixes = false
simplified = false

6. Additional resources