smarterlabs / omni

Omni-Directional Documents (.omni, .odd)

Omni-Directional Documents (.omni, .odd)

Note: All packages in this monorepo should be considered a work-in-progress. APIs may change dramatically.

Think of Omni-Directional Documents as "smart markdown files" that are capable of doing things such as variable interpolation between files, file bundling, using multiple languages in one file, and more. Since the syntax is 90% markdown, you can benefit from linting and code highlighting that you get in markdown file code blocks.

Example .omni file

Current Packages

• Omni Core: A JS module that acts as the core of the Omni compiler
• PHP Language Plugin: Enables PHP usage in .omni files
• JavaScript Language Plugin: Enables JS usage in .omni files
• Yaml Language Plugin: Enables Yaml config in .omni files
• Interpolation Plugin: Enables string interpolation in .omni code blocks
• VS Code Omni Extension: VS Code extension that enables code highlighting for .omni and .odd files

Directives

Note: More on the way!

config

A code block with a config directive is usually used to give instructions to Omni about how a file should be run or processed.

run

A code block with a run directive will execute the code block every time the file is processed. This can be useful for fetching data from an API to pass to another code block, or logging out debug information about the file that is being processed.

export

A code block with the export directive will export the code block to its own file after it has been processed

Directive aliases

You can create your own directives with directive aliases:

const omni = new Omni({
	input: `example`,
	output: `dist`,
	aliases: {
		script: `export:../dist/js/scripts/*.js`,
		style: `export:../dist/css/styles/*.css`,
	},
})

export default omni

And then use these directives:

```js script
console.log(`I was exported to another directory via alias!`)
```

```css style
body{
	margin: 0;
}
```

The script and style aliases will use the export directives in the config and export to thier respective locations.

Use Cases

• Using component-style patterns with frameworks that don't support them
• Keeping documentation with code
• Keeping tests with code
• Coordinating events between server and client side code in a decoupled environment
• Rapid prototyping in your documentation
• Working with multiple frameworks simultaneously
• Getting backend devs more familiar with front end or front end devs more familiar with backend
• Expressing user flow in production code

omni's Issues

Set up monorepo

File deletion

From my notes:

• File deletion
  • Export plugin should keep a map in memory of all files and their outputs
    • key=output
    • value=array of .omni files
  • Export plugin should also keep an in memory array of all .omni files

Readme in each package

CLI package

Functioning shared variables

Bundle

Ignore globs in config

Publish VS Code extension

PHP plugin

Eject plugins that don't work in client

So we can work towards a browser sandbox.

Check on ignore _*.omni files on watch/save

Process directory

Build script

Convert watcher to plugin

Event hooks

Core package

.npmignore

Merge config blocks instead of converting them to JSON

Build or watch with CLI args

Don't process commented out code blocks

Delete files when code blocks are removed

Check with file map to make sure it's not being exported via another .omni file.

Global variables in config

Directive aliases

alias:liquid-snippet

Instead of:

export:../theme/src/snippets/*.liquid

config:

import omniTemplates from '@smarterlabs/omni-templates'

omniTemplates({
 'liquid-snippet': data => {
    
  }
})

Diagram in readme

Show file contents on a chart:

• component.omni
• terminal input
• output
  • terminal output
  • file outputs

Ignore files option with globs

Sandbox package

CLI as plugin

Documentation

String replace plugin

If applied to the entire markdown file, it could be useful for name replacing in license, and readme files.

Finish vs code plugin manifest

https://code.visualstudio.com/api/references/extension-manifest

Publish packages on npm

Scope plugin

Autogenerate license files

Quickstart in main docs

Goal is a HTML/CSS/JS app.

Includes plugins for JS, Yaml, interpolation, and CLI.

Publish to npm with GH actions

Require support

Currently have to: const omniYAML = require(@smarterlabs/omni-yaml).default

Liquid plugin

Copy files with globs

omni-config.yaml

Help and version in CLI

omni-core package

@smarterlabs/omni package should be the core with some other plugins baked in.

Publish to npm via GH actions

Main config block

No interpolate directive on configs

interpolate:
  _scope_: nav
otherSetting: true

instead of:

_scope_: nav

otherSetting: true

Watch and transpile

File extensions in config

JavaScript plugin

Import plugin(s)

Allows an import to be declared in config that cascades into code blocks. Could be used to easily import JS, SCSS, and Liquid files with one declaration.

Tests

Process blocks in the order that they are encountered