Advanced Usage

All CLI options are available with the helper flag docker run ghcr.io/this-is-tobi/docpress -h :

Usage: docpress [options] [command]

Build your doc website faster than light ⚡️⚡️⚡️

Options:
  -b, --branch <string>                Branch used to collect Git provider data. Defaults to each repository's own default branch when not set.
  -c, --extra-public-content <string>  List of comma separated additional files or directories to process Vitepress public folder.
  -C, --config <string>                Path to the docpress configuration file.
  -f, --forks                          Whether or not to create the dedicated fork page that aggregate external contributions.
  -g, --git-provider <string>          Git provider used to retrieve data.
                                       Values should be "github" or "gitlab".
                                       (default: "github")
  -h, --help                           display help for command
  -l, --last-updated                   Whether or not to inject each page's last Git commit date as Vitepress "lastUpdated" frontmatter.
  --log-level <string>                 Verbosity of the CLI output. Values should be "error", "warn", "info", "trace" or "debug". Defaults to "info", or to the LOG_LEVEL environment variable when set.
  -p, --extra-header-pages <string>    List of comma separated additional files or directories to process Vitepress header pages.
  -r, --repos-filter <string>          List of comma separated repositories to retrieve from Git provider. Default to all user's public repositories.
  -t, --extra-theme <string>           List of comma separated additional files or directories to use as Vitepress theme.
  -T, --token <string>                 Git provider token used to collect data.
  -U, --usernames <string>             List of comma separated Git provider usernames used to collect data.
  -v, --vitepress-config <string>      Path to the vitepress configuration file.
  -V, --version                        output the version number
  --website-tagline <string>           Website tagline.
  --website-title <string>             Website title.

Commands:
  build [options]                      Build vitepress website.
  fetch [options]                      Fetch docs with the given username(s) and git provider.
  prepare [options]                    Transform doc to the target vitepress format.

Filter Repositories

The -r or --repos-filter option allows you to specify which repositories to include or exclude when generating documentation. This option accepts a comma-separated list of repository names and can include exclusions by prefixing a repository name with !.

• Including specific repositories: To generate documentation for specific repositories, provide their names separated by commas. For example, -r 'repo1,repo2' will retrieve documentation only for repo1 and repo2.
• Excluding repositories: To exclude certain repositories, prefix their names with !. For instance, -r '!repo1,!repo2' will retrieve all public repositories except repo1 and repo2.

Only public, non-fork repositories are fetched.

Vitepress Configuration

Vitepress configuration can be customized via a JSON configuration file, specified with the -v or --vitepress-config option. This file lets you adjust Vitepress options like the site title, navigation structure, footer, and plugins.

Key configurable options include:

• title: The title of the generated site.
• description: A description of the site (used for SEO).
• themeConfig: The theme configuration, including navigation and header links.
• markdown: Options to customize Markdown rendering.

Basic Vitepress configuration example:

{
  "title": "My Project Documentation",
  "description": "A site generated by Docpress",
  "themeConfig": {
    "socialLinks": [
      { "icon": "github", "link": "https://github.com/this-is-tobi" }
    ],
    "outline": [2, 4]
  }
}

Vitepress Theme

The -t or --extra-theme option allows users to provide additional files or directories that will be integrated into the VitePress theme dynamically. This enables users to enhance or completely customize the look and feel of their documentation site by adding their own components, styles, and other assets.

When using this option, the provided files are processed and registered automatically by Docpress. This means you can include custom Vue components, CSS/SCSS styles, JavaScript files, and other assets to complement or replace the default theme functionality.

How It Works

1. Dynamic Asset Registration:

• All files provided through --extra-theme are dynamically loaded and made available in the VitePress environment.
• Vue components are automatically registered globally, allowing you to use them in your Markdown files without additional imports.
• CSS/SCSS files are globally applied to ensure your styles are reflected across all pages of your documentation.

2. Supported File Types:

• .vue: Vue components are registered dynamically. The name of the component is derived from the filename.
• .css or .scss: Stylesheets are applied globally to enhance or override existing styles.
• .js or .ts: JavaScript or TypeScript files can be used to add logic or utilities.
• Static assets like .png, .jpg, .svg, etc., are included as part of the final build and are accessible in your documentation.

3. Fallback to Default Theme:

• Even if custom theme files are provided, the default Docpress/VitePress theme remains accessible. Your custom components and styles are layered on top of the existing theme, allowing for a hybrid or fully customized experience.

Usage

You can pass one or more file paths (comma-separated) to the --extra-theme option. For example:

npx @tobi-or-not/docpress -U <username> -t './custom-theme/components,./custom-theme/styles'

In this example:

• The components directory contains custom Vue components.
• The styles directory contains CSS/SCSS files to override or enhance the default styles.

Common Use Cases

• Adding Custom Components:
  • Create a CustomHeader.vue or CustomFooter.vue component and include it in the theme. These components can then be used in your Markdown files or layouts.
• Applying Custom Styles:
  • Include a styles.css file to define your own branding styles (e.g., colors, fonts, spacing).
• Extending Functionality:
  • Add JavaScript utilities or TypeScript logic for interactive elements or advanced functionality.
• Static Assets:
  • Include logos, background images, or icons that your theme uses to create a personalized appearance.

Example Directory Structure

Suppose you have the following directory structure for your custom theme:

custom-theme/
├── components/
│   ├── CustomHeader.vue
│   └── CustomFooter.vue
├── styles/
│   ├── theme.css
│   └── overrides.scss
└── assets/
    ├── logo.png
    └── background.jpg

By running the following command:

npx @tobi-or-not/docpress -U <username> -t './custom-theme'

Docpress will:

1. Register CustomHeader.vue and CustomFooter.vue as global components.
2. Apply the styles defined in theme.css and overrides.scss.
3. Include logo.png and background.jpg in the final build, making them accessible in your documentation.

Important Notes

• Ensure that your custom files do not conflict with the existing theme structure unless your intent is to override default behavior.
• Avoid including unnecessary or unused files to keep the build efficient.
• Static assets like images and fonts will be copied as-is into the final build directory, so ensure they are optimized for web use.

This flexibility allows you to create a fully customized, professional documentation experience tailored to your needs.

Extra Header Pages

With the -p or --extra-header-pages option, you can add additional pages to the Vitepress website header, such as privacy policies, advanced user guides, or links to external resources.

This option accepts a comma-separated list of Markdown files or directories containing Markdown files. These pages will be included as-is in the final website and automatically added to the navigation bar at the top of each page on the generated site.

All specified extra-header-pages must be in Markdown format and can include any Vitepress-compatible content, such as links, images, and other documentation elements.

Extra Public Content

The -c or --extra-public-content option allows you to include additional static assets in the Vitepress public folder. This is useful for adding content that needs to be accessible across all pages of the documentation, such as custom icons, logos, or other assets.

These files or directories will be copied directly into the public folder and will be available as static resources on the final website.

Common use cases for extra-public-content include:

• Adding branding assets: For example, including a custom favicon (favicon.ico) or logo (logo.png) that will display on every page.
• Providing downloadable files: Such as PDF guides, policy documents, or downloadable images that users may need quick access to.
• Supplementing media files: Including additional images, icons, or background files that you may want to reference across different parts of your documentation.

This option accepts a comma-separated list of file or directory paths.

Ensure that any files you add are optimized for the web, as large or uncompressed files may impact site performance.

All files and directories specified with extra-public-content are directly accessible at the root of the final site, making it easy to link to them within your Markdown files (e.g., using /logo.png in an img tag).

Fork Contributions Page

The -f or --forks option generates a dedicated page showcasing all forked repositories where the user's contributions have been successfully merged into the original source repositories.

NOTE

The forks page is only available with the github provider: the GitLab API does not expose the contributor identity needed to match merged contributions. This feature is ideal for creating a centralized portfolio or documentation to highlight the user's collaborative work and contributions across multiple projects.

By aggregating these repositories, the page serves as both a recognition of the user’s contributions and a historical archive of projects influenced by their efforts. It emphasizes the impact of these contributions and celebrates the investment made in community and open-source projects.

Common Use Cases

• Showcasing user contributions: Highlight the breadth of repositories where the user has made meaningful contributions.
• Building a contribution portfolio: Create a centralized "museum" of merged pull requests to demonstrate the user's influence across projects.
• Encouraging collaboration: Inspire others by showing how individual contributions can make a significant difference in the broader ecosystem.
• Archiving collaborative efforts: Preserve a historical record of impactful contributions and projects influenced by the user.

Generated Forks Page

When this flag is enabled, the tool creates a markdown page (docs/forks.md that will be available in header as Forks) listing all forked repositories where the user's pull requests have been merged into the original repositories. The page typically includes details such as:

• Repository name
• Repository description
• Repository stars counter

This page acts as a dynamic portfolio of contributions, making it an excellent resource for professionals, developers, and community members who wish to document their work and demonstrate their impact across various projects.

Forks With Extra Theme

If this option is used together with an extra theme (-t / --extra-theme), you can override the default fork page presentation by providing your own ForkPage.vue layout in your custom theme. Docpress registers the theme files first, so a fork-page layout supplied through --extra-theme takes precedence over the built-in one.

Docpress Configuration

Docpress can be configured with an external JSON configuration file specified by the -C or --config option. This file allows you to set Docpress parameters to automate and customize the documentation fetching and generation process. Key options that can be configured include:

• usernames: List of comma separated Git provider usernames used to collect data (equivalent to the -U CLI option).
• logLevel: Verbosity of the CLI output, one of error, warn, info, trace or debug (equivalent to --log-level).
• reposFilter: List of repositories to include or exclude (equivalent to the -r CLI option).
• branch: Branch from which documentation will be fetched (equivalent to -b). When omitted, each repository's own default branch is used, so repositories on master, develop, etc. are handled correctly.
• gitProvider: Git provider used to retrieve data, github or gitlab (equivalent to -g).
• lastUpdated: Whether or not to inject each page's last Git commit date as Vitepress lastUpdated frontmatter (equivalent to -l).
• extraHeaderPages: Additional pages to include in the website header (equivalent to -p).
• extraPublicContent: Additional content for the Vitepress public folder (equivalent to -c).
• extraTheme: Files or folders to customize the Vitepress theme (equivalent to -t).
• forks: Whether or not to create the forks page documentation (equivalent to -f).
• vitepressConfig: Inline Vitepress configuration object merged into the generated site config.

Example JSON configuration:

{
  "usernames": ["user1"],
  "reposFilter": ["!repo1", "!repo2"],
  "branch": "main",
  "extraHeaderPages": ["./extras-headers", "header2.md"],
  "extraPublicContent": ["./extras-public", "favicon.ico", "logo.png"],
  "extraTheme": ["./extras-theme/styles", "./extras-theme/components", "./more.css"],
  "forks": false,
  "vitepressConfig": {
    "title": "My Project Documentation",
    "description": "A site generated by Docpress",
    "themeConfig": {
      "socialLinks": [
        { "icon": "github", "link": "https://github.com/this-is-tobi" }
      ],
      "outline": [2, 4]
    }
  }
}

When collecting from a single user, each repository is served at the root of the site (e.g. /<repo_name>/introduction).

When collecting from multiple users, generated pages are namespaced by username to avoid collisions between users that own a repository with the same name. Both the on-disk documentation folder and the site routes are prefixed with the username (e.g. /<username>/<repo_name>/introduction). Because of this, repository filters must also specify the user prefix (with the format <username>/<repo_name>) :

{
  "usernames": ["user1", "user2"],
  "reposFilter": ["user1/repo1", "!user2/repo2"],
  "branch": "main",
  "extraHeaderPages": ["./extras-headers", "header2.md"],
  "extraPublicContent": ["./extras-public", "favicon.ico", "logo.png"],
  "extraTheme": ["./extras-theme/styles", "./extras-theme/components", "./more.css"],
  "forks": false,
  "vitepressConfig": {
    "title": "My Project Documentation",
    "description": "A site generated by Docpress",
    "themeConfig": {
      "socialLinks": [
        { "icon": "github", "link": "https://github.com/this-is-tobi" }
      ],
      "outline": [2, 4]
    }
  }
}

Git Provider Selection

The -g or --git-provider option selects the platform used to collect data. Docpress supports github (default) and gitlab (gitlab.com). With gitlab, the given names can be usernames or group paths, and the fetched repositories are the public projects of that user or group.

Log Level Selection

The --log-level option (or the logLevel config key) controls how much detail Docpress prints while it runs. Accepted values are error, warn, info (default), trace and debug — each level includes all the ones before it, so debug prints everything and error prints only failures.

npx @tobi-or-not/docpress -U <username> --log-level debug

Under the hood, each value maps to a numeric LOG_LEVEL environment variable (error = 10, warn = 20, info = 30, trace = 40, debug = 50). Setting LOG_LEVEL directly still works and can be more convenient in environments where passing CLI flags is inconvenient (e.g. Docker or CI):

LOG_LEVEL=50 npx @tobi-or-not/docpress -U <username>

--log-level (or logLevel in the config file) takes precedence over the LOG_LEVEL environment variable when both are set.

Git Provider Token Option

When using the Docpress tool to fetch data from GitHub or GitLab, you have the option to provide a personal access token using the -T flag. This token is important as it allows you to authenticate your requests, which can help increase your request limits on the provider API.

To avoid exposing the token on the command line (where it can be captured by process listings, shell history or CI logs), you can also provide it through an environment variable. The token is resolved with the following precedence: the -T flag, then DOCPRESS_TOKEN, then the provider-specific GITHUB_TOKEN (for github) or GITLAB_TOKEN (for gitlab).

# Equivalent to passing -T, but keeps the token off the command line
GITHUB_TOKEN=<your-token> npx @tobi-or-not/docpress -U <username>

Utilizing a personal access token not only helps you avoid rate limiting issues but also enhances the reliability of data retrieval for your documentation projects.

For further details on how authentication affects rate limits and other considerations, please refer to the official GitHub documentation on Rate limits for the REST API.