Product
Introducing Socket Optimize
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.
graph-docs-cli
Advanced tools
_This is an experimental package - I'm looking forward to your feedback on how to improve it._
This is an experimental package - I'm looking forward to your feedback on how to improve it.
Revolutionise your docs by building a knowledge graph from markdown.
graphviz
yarn add -D graph-docs-cli
modules
, and create two files: one.md
and two.md
two.md
, add this markdown frontmatter:---
deps: [one] # the filename of the module, without the .md extension
---
yarn graph-docs dev "./modules/*.md"
My name's Matt, and I'm a developer advocate at Stately. I was working on restructuring XState's documentation, and I noticed something.
The docs were not designed to be read in order. On each page, they referenced pieces of information that the viewer hadn't understood yet. There was advanced information mixed in to beginner concepts. Fundamental subjects were left too late. The docs were not organised around a desired learning path for the user.
I wanted to change this - and, as a developer, I wanted a data structure to help me. I chose a directed graph. I wanted to extract each piece of information from the docs into its own, small module - and have each module express its direct dependencies to other modules.
For instance - let's say you want to understand how to write an arrow function in JavaScript: () => {}
. To understand that, you'll need to walk a path like this:
Arrow functions -> Normal functions
Normal functions -> Variables
Variables -> What is JavaScript?
Which, when put through graphviz, looks like this:
Let's imagine you also wanted to add const vs var vs let
- you don't need to know about arrow functions for that, but you do need to know about variables:
What you end up with is a graph of optimal paths to learn any piece of information. This is extremely powerful for several reasons:
Modules of information are similar to modules of code - both can contain circular dependencies. In a docs page, this can result in two pieces of information where understanding one depends on understanding the other. This can result in a terrible learning experience. The learner has to read both modules fully, and only at the end (or perhaps on a re-read) will they understand the full picture.
In graph-docs, circular dependencies are not allowed. If you attempt it, you'll get a maximum call stack exceeded
error in the CLI.
This constraint forces you to resolve the circular dependency the way you would in code - by either:
This is also what makes graph-docs
different from something like Roam/Obsidian. These tools are fantastic for note-taking. But the fact that they allow circular dependencies makes them unoptimized for readers other than their author.
When your graph gets to 100+ modules, it can be hard to see the wood through the trees. You'll naturally want to start grouping them together.
Most docs sites will need a kind of grouping anyway, for menu organisation etc.
To add groups, follow these steps:
{
"groups": [
{ "id": "basics", "color": "red" },
{ "id": "advanced", "color": "forestgreen" }
]
}
group: advanced
to the frontmatter of one of the files, for instance:---
group: advanced
---
You'll see the relevant node in the graphviz will turn green.
Currently, there are no custom integrations with docs platforms as part of this package. We should add some!
For the XState docs, we've written a custom integration where we construct pages out of modules using a handlebars-style syntax:
# States
<!-- Links to the states.md module -->
{{ states }}
## Final States
<!-- Links to the final-states.md module -->
{{ final-states }}
(This isn't open-source yet, but will be when we release it.)
But we should offer this as part of graph-docs
. Any thoughts appreciated in issues!
0.0.11
c2e98bd
Thanks @mattpocock! - Fixed a bug where you needed git with at least one commit to run graph-docs devFAQs
_This is an experimental package - I'm looking forward to your feedback on how to improve it._
The npm package graph-docs-cli receives a total of 2 weekly downloads. As such, graph-docs-cli popularity was classified as not popular.
We found that graph-docs-cli demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.
Product
We're excited to announce that Socket now supports the Java programming language.
Security News
Socket detected a malicious Python package impersonating a popular browser cookie library to steal passwords, screenshots, webcam images, and Discord tokens.