electron / electron-docs

Fetch Electron documentation as raw markdown strings

electron-docs

This package consumes the electron/electron repo in search of markdown files, and returns an array of file objects with stringified file contents.

It is used by Electron's docs linter.

Installation

npm install electron-docs --save

Programmatic Usage

Require the function and call it with any of the following:

• A remote branch name, like main
• A version number, like 1.4.4
• A version number that starts with a v, like v1.7.0
• A commit SHA, like 76375a83eb3a97e7aed14d37d8bdc858c765e564
• A local directory, like ~/my/path/to/electron/

const electronDocs = require('electron-docs')

electronDocs('main').then(function(docs) {
  // docs is an array of objects, one for each markdown file in /docs
})

Each object in the docs array looks like this:

{
 slug: "windows-store-guide",
 filename: "docs/tutorial/windows-store-guide.md",
 markdown_content: "# Windows Store Guide\n\n..."
}

When fetching docs from a local directory, be sure to use a full path:

const path = require('path')
const docsPath = path.join(__dirname, 'docs')
electronDocs(docsPath).then(function(docs) {
  // ...
})

If you prefer node-style callbacks instead of promises, those are supported too:

electronDocs('1.0.0', function(err, docs) {
  console.log(err, docs)
})

CLI Usage

Add this to your package.json file:

{
  "scripts": {
    "docs": "electron-docs > docs.json"
  }
}

When you run npm run docs, the module writes the stringified JSON object to stdout, and the output is piped into a file.

stdout ftw!

Tests

npm i && npm t

Dependencies

• got: Simplified HTTP requests
• gunzip-maybe: Transform stream that gunzips its input if it is gzipped and just echoes it if not
• node-dir: asynchronous file and directory operations for Node.js
• ora: Elegant terminal spinner
• path-exists: Check if a path exists
• pify: Promisify a callback-style function
• semver: The semantic version parser used by npm.
• tar-fs: filesystem bindings for tar-stream

Dev Dependencies

• tap-spec: Formatted TAP output like Mocha's spec reporter
• tape: tap-producing test harness for node and browsers

License

MIT

electron-docs's Issues

Please update tar-fs dependency

Hello,

could you please update the tar-fs dependency to at least major-version 2 to get rid of the vulnerable bl package (CVE-2020-8244).

A buffer over-read vulnerability exists in bl <4.0.3, <3.0.1 and <2.2.1 which could allow an attacker to supply user input (even typed) that if it ends up in consume() argument and can become negative, the BufferList state can be corrupted, tricking it into exposing uninitialized memory via regular .slice() calls.

Please also release a new version.

Thanks,
Gregor

Need some streams guidance

Hey @maxogden, @mafintosh, and @sindresorhus!

I'm fetching a tarball from GitHub and extracting files out of it. The tarball is saved to disk to make subsequent executions faster:

  if (exists(tarball)) {
    fs.createReadStream(tarball)
      .pipe(gunzip())
      .pipe(extractor)
      .on('error', function (e) {
        callback(e)
      })
  } else {
    got.stream(tarballUrl)
      .pipe(fs.createWriteStream(tarball))
      .on('end', function () {
        fs.createReadStream(tarball)
          .pipe(gunzip())
          .pipe(extractor)
          .on('error', function (e) {
            callback(e)
          })
      })
  }

This is ugly though, and potentially unsafe as noted in the path-exists README:

In particular, checking if a file exists before opening it is an anti-pattern that leaves you vulnerable to race conditions: another process may remove the file between the calls to fs.exists() and fs.open(). Just open the file and handle the error when it's not there.

However, the idea of setting up a stream to read the file and creating an error handler to detect an ENOENT code seems cumbersome to me.

Tell me, O streaming wizards: Is there a more glamorous way to do this?

I think I'm looking for a module that streams files from disk or downloads them if they don't yet exist.

Add support to pass a custom git repo

Curently support to pass a local path but that would be great to support: git+https://[email protected]/MyName/electron.git#my_branch