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. (default: "main")
  -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". (default: "github")
  -h, --help                           display help for command
  -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, --username <string>              Git provider username used to collect data.
  -v, --vitepress-config <string>      Path to the vitepress configuration file.
  -V, --version                        output the version number

Commands:
  build [options]                      Build vitepress website.
  fetch [options]                      Fetch docs with the given username 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 vitepress.config.js 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. 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 with extra theme, the

Docpress Configuration

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

• username: Git provider username (usually GitHub) to fetch repositories (equivalent to the -U CLI option).
• reposFilter: List of repositories to include or exclude (equivalent to the -r CLI option).
• branch: Default branch from which documentation will be fetched (equivalent to -b).
• 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 -f).

Example JSON configuration:

{
  "username": "my-github-username",
  "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,
  "vitepress": {
    "title": "My Project Documentation",
    "description": "A site generated by Docpress",
    "themeConfig": {
      "socialLinks": [
        { "icon": "github", "link": "https://github.com/this-is-tobi" }
      ],
      "outline": [2, 4]
    }
  }
}

GitHub Token Option

When using the Docpress tool to fetch data from GitHub, 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 GitHub API.

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.