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

snipsync

v1.10.0

Published

Sync docs with github repo code snippets

Downloads

149

Readme

Snipsync

Snipsync makes sure your documented code snippets are always in sync with your Github repo source files.

Prerequisites

This tool requires Node v15.0.0 or above (recommended 15.2.1) and Yarn.

Install

Yarn:

yarn add snipsync

Configure

Create a file called "snipsync.config.yaml" in the project root. This file specifies the following:

  • origins: The Github repositories or local files where the tool will look for source code snippets.
  • targets: The local directories that contain the files to be spliced with the code snippets.

The origins property is a list of objects that have one of the following 2 formats:

  1. owner, repo, and optionally ref: Pull snippets from a GitHub repo
  2. files: a set of strings:
  • pattern: Relative path to load snippets from. Supports glob syntax.
  • owner: GitHub repo owner name, to be used in the source snippets links
  • repo: Name of the repo snipsync is being used in, to link to the source snippets
  • ref: (Optional, defaults to main) Used for writing source snippet links.

If the ref key is left blank or not specified, then the most recent commit from the main branch will be used. If the enable_source_link key in features is not specified, then it will default to true. If the enable_code_block key in features is not specified, then it will default to true.

The allowed_target_extensions key in features lets you set a list of extensions to scan. Specify extensions like [.md,.txt]. If the allowed_target_extensions key in features is not specified, then it defaults to an empty array ([]) and all files are scanned.

The enable_code_dedenting key in features lets you remove leading spaces from indented code snippets. This is handy when you're including a snippet of code within a class or function and don't want to include the leading indentation. This is false by default.

Example of a complete snipsync.config.yaml:

origins:
  - owner: temporalio
    repo: go-samples
    ref: 6880b0d09ddb6edf150e3095c90522602022578f
  - owner: temporalio
    repo: java-samples
  - files:
      pattern: ./sample-apps/typescript/*.ts
      owner: temporalio
      repo: documentation
      ref: main

targets:
  - docs
  - blog

features:
  enable_source_link: false
  enable_code_block: false
  allowed_target_extensions: [.md]
  enable_code_dedenting: false

Example of a bare minimum snipsync.config.yaml:

origins:
  - owner: temporalio
    repo: go-samples
targets:
  - docs

Comment wrappers

Use comments to identify code snippets and the locations where they should be merged.

Source code

In the source repo, wrap the code snippets in comments with a unique snippet identifier like this:

// @@@SNIPSTART hellouniverse
func HelloUniverse() {
	fmt.Println("Hello Universe!")
}
// @@@SNIPEND

In the example above, "hellouniverse" is the unique identifier for the code snippet.

Unique identifiers can contain letters, numbers, hyphens, and underscores.

Target files

In the target files wrap the location with comments that reference the identifier of the code snippet that will be placed there:

<!--SNIPSTART hellouniverse-->
<!--SNIPEND-->

In the example above, the "hellouniverse" code snippet will be spliced between the comments. Any text inside of the placeholders will be replaced by the code snippet when the tool runs. The tool will automatically specify the code type for markdown rendering. For example, if the source file ends in ".go" then the code section will be written like this: ```go

Per-snip features

To customize how a single snip is rendered, add a JSON feature configuration in the snip start line.

<!--SNIPSTART hellouniverse {"enable_source_link": false, "enable_code_block": false}-->
<!--SNIPEND-->

Selected lines

A single source code snippet may be used in multiple places. If so, you may wish to customize which lines are rendered. Add a "selected" configuration to the snip start line.

<!--SNIPSTART hellouniverse {"selectedLines": ["1", "3-5"]}-->

The line numbers are relative to the snippet, not the source file.

The feature supports multiple selections as either a single line or a range.

Highlighed lines

Some frameworks support highlighting code lines in code blocks. If so, you can add a "highlights" configuration to the snip start line.

<!--SNIPSTART hellouniverse {"highlightedLines": "{1, 3-4}"}-->

The line numbers are relative to the published snippet. That means that if selectedLines is used, the line numbers to highlight are relative to the pared down selection that is merged into the Markdown file.

If you use Docusuarus, you just need to add some additional CSS: https://docusaurus.io/docs/markdown-features/code-blocks#line-highlighting

Regex snipping

Instead of specifying a set of line numbers to snip, you can use regular expression patterns to mark the start and end of a snip. Specify a startPattern and an endPattern:

<!--SNIPSTART hellouniverse {"startPattern" : "const \\{ greet", "endPattern": "\\}\\)"} -->

Run

From the root directory of your project run the following command:

yarn snipsync

Remove snippets

In some cases, you may want to remove the snippets from your target files. Use the --clear flag to do that:

yarn snipsync --clear

Development

The snipsync tool is set up to run its own functionality during development. Git ignores the snipsync.config.yaml file and the /docs directory within the package itself.

While developing, you can add files to /docs define the snipsync.config.yaml file, and run yarn dev to run snipsync from the root of the repo.

To clear the snippets run yarn dev --clear

Testing

Run yarn test from the root of the repo to run the testing suites.