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

@factorial/docs

v0.5.3

Published

_Factorial Docs_ lets you quickly create a static documentation site based on Markdown files in your project.

Downloads

78

Readme

Factorial Docs

Factorial Docs lets you quickly create a static documentation site based on Markdown files in your project.

Installation

npm i @factorial/docs

or

yarn add @factorial/docs

Then create a .eleventy.js (or any name of your choice) with the following content:

const config = require("@factorial/docs/config");

module.exports = function (eleventyConfig) {
    return config(eleventyConfig, {
        … // options (see below)
    });
};

Options

All options are optional.

  • projectName: string (default: "Factorial") The name of the project, e.g. "phabalicious"
  • githubUrl: string|null (default: null) The URL the of the public repository, e.g. "https://github.com/factorial-io/phabalicious"
  • heroImage: object
    • src: string
    • width: number
    • height: number
  • logo: object | false
    • src: string (default: "https://logo.factorial.io/color.png")
    • width: number (default: 30)
    • height: number (default: 42)
  • footerLogo: object | false (default: logo)
    • src: string
    • width: number
    • height: number
  • twitter: string
  • input: string (default: ".") The directory in which you markdown files and assets are located
  • output: string (default: "build") The directory where eleventy writes the build files to
  • openSource: boolean (default: false) Defines if this project is an open source project or not
  • algolia: object Configuration object for the algolia search (Keys: appId, apiKey, indexName)
  • menu: array (default: null) An array to specifiy the menu entries (see Specifying the menu)

Creating the homepage

In your input directory, please create an index.md with the following content:

---
homepage: true
hero_text:
tagline:
action_text:
action_link:
features:
  - title:
    details:
    icon:
footer:
---

Specifying the menu

By default the entries in the menu are in no peticular order. If you want to control the order or hide certain menu entries, you can define an array like the following:

[
  {
    path: "documentation",
    children: ["guide", "installation", "usage"],
  },
  {
    path: "blog",
    children: ["introduction", "architecture"],
  },
  "changelog",
];

Ideally the folder structure reflects the menu structure. That means, for the example above, the folder structure would look like this:

├─ documentation/
│  ├─ README.md / index.md
│  ├─ guide.md
│  ├─ installation.md
│  ├─ usage.md
├─ blog/
│  ├─ README.md / index.md
|  ├─ introduction.md
|  ├─ architecture.md
├─ changelog.md

This would create URLs like the following:

  • documentation/
  • documentation/guide.html
  • documentation/installation.html
  • documentation/usage.html
  • blog/
  • blog/introduction.html
  • blog/architecture.html
  • changelog.html

If you prefer to have for example documentation.html instead of documentation/, you could also create a documentation.md in the root directory instead of a README.md or index.md inside documentation/.

If you do not want to move the files into a directory, but keep the structure in the menu, you could create the files like this:

├─ documentation.md
├─ guide.md
├─ installation.md
├─ usage.md

In this case, you need to add parent to the front matter of a page:

---
parent: documentation
---

This would create URLs like the following:

  • documentation.html
  • guide.html
  • installation.html
  • usage.html

Adding a meta description

To add a meta description, you can use the front matter of a page:

---
meta_description: …
---

Usage

HOST is hostname of the docs, for example "https://docs.phab.io". This is important to generate a correct sitemap.

NOTE: The following example are for yarn users. If you use npm, you need to add a script to your package.json and then use npm run … instead.

Build

FDOCS_HOST=<HOST> yarn fdocs

With individual config name

FDOCS_HOST=<HOST> yarn fdocs --config=.config.js

Development server

FDOCS_HOST=<HOST> yarn fdocs --config=.config.js --serve

With individual config name

FDOCS_HOST=<HOST> yarn fdocs --config=.config.js --serve

Sitemap

A sitemap.xml is automatically created. Please note that when using --serve, it is only created once when the process starts.