npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@tobi-or-not/docpress

v0.5.1

Published

This project aims to automate the construction of documentation website based on a Github username and optionally a list of repositories.

Downloads

516

Readme

Docpress :zap:

This project aims to automate the construction of documentation website based on a Github username and optionally a list of repositories.

Explanation

Docpress automates the process of downloading documentation files from specified GitHub repositories. Here's how it works:

  1. Repository Documentation Retrieval:

    • The program checks if a docs/ folder is present at the root level of each specified repository.
    • If the docs/ folder exists, the entire folder will be downloaded, including all its contents.
    • If the docs/ folder is not found, only the README.md file will be downloaded.
  2. Static Website Generation:

    • After retrieving the documentation files, Docpress generates a static website using VitePress. This framework allows for the creation of fast and customizable documentation sites.

For optimal use of Docpress, please check the rules section to understand the conventions and guidelines that will ensure that everything works correctly. By following these rules, you can maximize the effectiveness of the documentation process.

Documentation

Website: https://this-is-tobi.com/docpress/introduction.

Table of Contents - md sources:

Quickstart

  1. Generate website using the Docpress docker image.

    docker run --name docpress --rm -v $(pwd)/docpress:/app/docpress:rw \
      ghcr.io/this-is-tobi/docpress -U <github_username>

    The dist folder is available at ./docpress/.vitepress/dist, ready to be served by a web server like Nginx, Apache, etc...

  2. Start an Nginx docker image using the generated static folder.

    docker run --name my-docs --rm -v ./docpress/.vitepress/dist:/usr/share/nginx/html:ro -p 8080:80 \
      docker.io/nginx
  3. Access the website at the following address : http://localhost:8080.

Options

CLI description :

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.

Usage methods

Docpress is available through both npm and Docker, so you can choose the installation method that best suits your environment.

Using npm (or other package managers)

If you prefer Node.js package managers like npm, pnpm, or bun, you can easily install and run Docpress without additional setup.

To run Docpress using npm:

npx @tobi-or-not/docpress -U <github_username>

[!TIP] If you’re using a package manager like pnpm or bun, simply replace npx with the corresponding command (pnpx or bunx) to execute Docpress.

Using Docker

Docpress also provides a Docker image, which is especially useful if you want to avoid installing dependencies directly on your system or if you’re working in a containerized environment. Using Docker ensures a consistent runtime environment.

To run Docpress with Docker:

docker run --rm -v $(pwd)/docpress:/app/docpress:rw ghcr.io/this-is-tobi/docpress -U <github_username>

In this command:

  • --rm removes the container after it stops, keeping your environment clean.
  • -v $(pwd)/docpress:/app/docpress:rw mounts the docpress directory in your current path to the container’s /app/docpress folder, allowing Docpress to store generated files locally.

Ensure Docker is installed and running on your system before using this method.

Both methods provide the same functionality, so you can choose the one that fits your setup or use case.

Rules

To ensure that the program functions correctly, please follow these conventions:

Repository name and structure

  • The script will only parse the docs/ folder located at the root level of the repository. This folder is used to import advanced documentation features, such as multi-page documentation, embedded images, and files.
  • Repositories whose name starts with a dot are processed, but the dot will be removed.

File naming and sorting

  • If a docs/ folder is present, all files within it will be sorted and renamed by removing any prefix numbers. This ensures that files appear cleanly in the generated website. For example, docs/01-get-started.md will be renamed to get-started.md.

Handling the root readme file

  • The README.md file located at the root of the repository will only be imported if there is no ./docs/01-readme.md file present. This allows you to differentiate between the general README and the advanced documentation introduction page.
  • For instance, you might use the README file for a table of contents that is not relevant in the context of the documentation website.

Link management

  • Any inline link in the ./README.md file that does not point to ./docs/** will be replaced with the corresponding GitHub link.
  • Similarly, any inline link in the ./docs/*.md files that does not reference ./docs/** will also be replaced with the appropriate GitHub link.

Project descriptions

  • The project description displayed on the home page of the generated website is extracted from the GitHub repository's description.

By adhering to these rules, you can ensure that your documentation is processed correctly and that it aligns with the intended structure and functionality of the generated site.