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

oranda

v0.0.3

Published

Create beautiful and simple HTML pages from your Readme.md files

Downloads

5

Readme

🐠 Oranda

Create beautiful and simple HTML pages from your Readme.md files

  • 🛠 No config
  • 👩‍💻 Code Highlighting
  • 💯 Emoji Support
  • ✨ Creates Static files
  • 🌎 OS Detection
  • 🏳️‍🌈 Pretty Pages
  • 🦄 Customizable
  • 🖼 Image minification
  • 🧠 Custom Meta Tags
  • 🇳🇱 CodeSandbox and iframe Support
yarn add oranda --dev
npm install oranda --save-dev

Usage

{
  ...
  "scripts": {
    "build:demo": "oranda",
    ....
  }

Usage with npx

If you just want a quick fancy HTML page from the Readme but don't care about running this in continuous deployment you can also use npx to run it as a one time thing.

npx oranda

By running this in the root folder you will also get a public folder

Options

Options can be placed in one of three ways:

  • .oranda.config.json placed in the root
  • oranda key in package.json
  • package.metadata.oranda section in the Cargo.toml

It can contain the following options:

| Option | Default | Description | | --------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | file | Readme.md, readme.md, or README.md | Your Readme.md name | | name | name in package.json/Cargo.toml | The project name that is in the title and the header | | logo | '' | The project logo that is in the header | | shareCard | '' | URL to social media preview image for meta tags (recommended size: 1200x628, URL cannot be relative) | | description | description in package.json/Cargo.toml | The project description for meta tags | | homepage | homepage in package.json/Cargo.toml | The project homepage for meta tags | | noHeader | false | Show no header and just the markdown content | | theme | light | Options are light and dark | | syntaxHighlight | { dark: 'poimandres', light: 'github-light'} | What syntax highlight theme to use in dark and light mode. All shikijs themes can be used | | favicon | '' | Favicon url or local path | | dist | public | To what folder to render your HTML | | styles | {} | Styles to apply to the page. Object or path to css/scss file | | additionalFiles | [] | Any other pages to create. It expects an array of paths of markdown files | | repository | repo in package.json/Cargo.toml | Link to point the github corner | | pathPrefix | Environment var PATH_PREFIX or / | Host your oranda files at e.g. /my-oranda-project | | meta | [] | Any extra meta tags you would like | | remoteStyles | [] | Array of any remote styles you want to include (eg: Google Fonts) | | remoteScripts | [] | Array of any remote scripts you want to include (eg: Google Analytics) | | deployment | {} | Deployment options for github pages. Accepts all options here | | downloads | {} | Links to download binaries or ways to install package, example below |

Example of downloads

Let's say you have an app that can be install in several operating systems, you can create an object like so:

{
  "downloads": {
    "linux": {
      "link": "https://my-app.com/my-app-x86_64-unknown-linux-musl.tar.gz",
      "description": "this is my description if I want one",
      "changelog": "https://my-app.com/changelog.md"
    },
    "windows": {
      "link": "https://my-app.com/my-app-x86_64-pc-windows-msvc.tar.gz"
    },
    "mac": {
      "link": "https://my-app.com/my-app-x86_64-apple-darwin.tar.gz"
    }
  }
}

Oranda will automatically try to recognize the user OS and highlight the correct OS and highlight that option.

There is an example of it on the CLI for Let's play retro games

This can also be used to demonstrate different package managers that one can use to install the package:

{
  "downloads": {
    "npm": {
      "text": "npm i oranda"
    },
    "yarn": {
      "text": "yarn add oranda"
    },
    "pnpm": {
      "text": "pnpm install oranda"
    }
  }
}

All objects accept the following keys:

{
  "text": "Any text you want to show like a way to install, this will be automatically highlighted as a bash script",
  "link": "Where can people download your package?",
  "description": "Any description you want to show the user before downloading",
  "changelog": "A link to your changelog"
}

Example of styles

For styles you can either use a style object like so and that will override the default styles applied. Like so:

{
  "styles": {
    "h1": {
      "color": "blue",
      "backgroundColor": "red"
    }
  }
}

Another option is to give the path to a local css or scss file. In this case you need to override any specificity issues. You can by using the #oranda id. Example:

body {
  background: #fff;
}

#oranda {
  h1 {
    text-transform: uppercase;
  }
}

Meta Tags

To create any meta tags it uses an array system like so:

  "meta": [
    { "name": "description", "content": "A cool page" },
    { "property": "robots", "content": "robots.txt" }
  ]

This will create the following HTML:

<meta name="description" content="A cool page" />
<meta property="robots" content="robots.txt" />

The first key on the object can have any name and will be applied as presented, the second one must have the name of content and will work as presented above.

Images

Any images linked in your markdown that are local will be minified and copied to your dist folder. If some image is not found it will be ignored.

GitHub Corner

The GitHub corner comes from either the repo option in your .oranda.config.json or from the repository url in your package.json. If none is present it will not be shown.

Lint

oranda also exports a command to let you lint all the markdown files you specified.

You can run this by using the lint command

"lint:md" : "oranda lint"

Deploy

oranda also exports a command to let you deploy your new site to GitHub pages

You can run this by using the deploy command

"deploy" : "oranda deploy"

Options for this can be passed in a deployment key in your config file. All options can be found here: https://github.com/tschaub/gh-pages#options

Acknowledgements

Contributors

| Sara Vieira💻 🎨 🤔 | Bruno Scheufler💻 | Siddharth Kshetrapal💻 | Jamon Holmgren💻 | Timothy💻 | Andrew Cherniavskii💻 | timkolberger💻 | | :---: | :---: | :---: | :---: | :---: | :---: | :---: |

License

MIT - see LICENSE