Aqua

Version v20.3.3

Introduction

Aqua acts as a preprocessor for Web Components and markdown parsers, mainly built to be compatible with Svelte, but it could also work in browsers natively as a callable API.

This parses markdown/markups and returns a styled HTMLElement block that could be injected to any DOM or directly replace the processed Node if used natively in a browser.

It only utilizes prism, everything else is built from the ground up using native Web APIs and modern CSS layouts, preprocessed to be compatible with both modern and old browsers.

Quick Start

Toggle
NumberingCopy
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ignatiusmb/aqua@20.3.3/lib/aqua.min.css" />
<script defer src="https://cdn.jsdelivr.net/npm/@ignatiusmb/aqua@20.3.3/lib/aqua.cbs.js"></script>
Use as highlighter function
Toggle
NumberingCopy
import Aqua from '@ignatiusmb/aqua';
const options = {
  highlight: (str, language) => Aqua.code.highlight(str, { language });
}

// Use it like so as 'markdown-it' options
const markIt = require('markdown-it')(options);

The output from the parsed block of code should then look like the code block above. There’s also a couple more examples below in the Modules / API section. This documentation is also built with Aqua.

You should be able to use highlight API from code with any markdown parser that allows you to handle the syntax highlighting yourself. This is basically the custom highlight function replacement, and it respects the DOM hierarchy by starting with the <pre> tag so there won’t be any unnecessary nesting happening.

Getting Started

The official recommended way to build with Aqua is to use Marqua.

Use in Node.js

via npm
Toggle
NumberingCopy
npm install @ignatiusmb/aqua

Use in Browser

Direct Include --> jsDelivr CDN
Toggle
NumberingCopy
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ignatiusmb/aqua@20.3.3/lib/aqua.min.css" />
<script defer src="https://cdn.jsdelivr.net/npm/@ignatiusmb/aqua@20.3.3/lib/aqua.min.js"></script>
Direct Include --> UNPKG CDN
Toggle
NumberingCopy
<link rel="stylesheet" href="https://unpkg.com/@ignatiusmb/aqua@20.3.3/lib/aqua.min.css" />
<script defer src="https://unpkg.com/@ignatiusmb/aqua@20.3.3/lib/aqua.min.js"></script>

Included Font Vars

Toggle
NumberingCopy
:root {
  --aqua-default: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', 'Rubik', 'Ubuntu', 'Roboto', sans-serif;
  --aqua-heading: 'Karla', sans-serif;
  --aqua-monospace: 'Fira Code', 'Inconsolata', 'Consolas', monospace;
}

/* Example */
body {
  font-family: var(--aqua-default);
}
header {
  font-family: var(--aqua-heading);
}
footer {
  font-family: var(--aqua-monospace);
}
Use your own binaries or through CDN
Toggle
NumberingCopy
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Rubik&display=swap">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Ubuntu&display=swap">

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Karla&display=swap">

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Fira+Code&display=swap">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inconsolata&display=swap">

Important Note

Aqua provides stylesheets and script files, linking or including the stylesheet is mandatory to display the elements properly. A custom reset is included as well so it makes quick prototyping a breeze, everything should display properly, and it works without any additional configuration.

1.0 - without bundler
Toggle
NumberingCopy
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ignatiusmb/aqua@20.3.3/lib/aqua.min.css" />
2.0 - with a bundler
Toggle
NumberingCopy
import '@ignatiusmb/aqua/lib/aqua.min.css';

On the other hand, there’s a couple of ways to use the script files. You can use and import the entire module through the CDN if you’re using it in the client-side. But, if you use the parser from the server-side, you can just bundle the callback script file with your website or include it in the head.

1.0 - Parsing in client-side
Toggle
NumberingCopy
<script defer src="https://cdn.jsdelivr.net/npm/@ignatiusmb/aqua@20.3.3/lib/aqua.min.js"></script>
2.0 - Parsing from server-side | With bundler
Toggle
NumberingCopy
import '@ignatiusmb/aqua/lib/aqua.cbs';
2.1 - Parsing from server-side | No bundler
Toggle
NumberingCopy
<script defer src="https://cdn.jsdelivr.net/npm/@ignatiusmb/aqua@20.3.3/lib/aqua.cbs.js"></script>

Modules / API

Aqua doesn’t have any named export by default, but it provides many props that has it, all available and listed below. First, import the entire module through its default export with the name Aqua.

Toggle
NumberingCopy
import Aqua from '@ignatiusmb/aqua';

Code.js

Toggle
NumberingCopy
const { cbs, highlight, highlightAll, init } = Aqua.code;

Aqua.code provides 4 public methods

  1. init - method used for client-side parsing
  2. cbs - all the needed callbacks for toolbar onclick events
  3. highlight - the highlighter function to parse code blocks
  4. highlightAll - wrapper to call Prism highlightAll function
Client-side usage
Toggle
NumberingCopy
<body>
  <pre class="aqua code-block" data-language="" data-title="">
  <!-- text to be preformatted -->
  </pre>

  <div id="root" class="container">
    <pre class="aqua code-block" data-language="" data-title="">
    <!-- text to be preformatted -->
    </pre>
  </div>
</body>

<script>
  // Defaults to document.body if no argument is passed
  // This will parse and highlight all <pre> tags
  // with class of 'aqua code-block' inside <body>
  Aqua.code.init();

  // Select tag with class of 'container' and id 'root'
  // as the starting element and will only parse
  // all <pre> tags inside tags with this class and id
  Aqua.code.init(document.querySelector('.container#root'));
</script>
Server-side usage | Simple
Toggle
NumberingCopy
const markIt = require('markdown-it')({ highlight: (str, language) => Aqua.code.highlight(str, { language }) });
Server-side usage | With title parsing
Toggle
NumberingCopy
const options = {
  highlight: (str, language) => {
    const strList = str.split('\n');
    const dataset = { language };

    // If the first line has a prefix of '~'
    // It will use the first line as the title
    if (strList[0][0] === '~') {
      dataset['title'] = strList[0].slice(1);
    }
    // Check if title exist and remove it from string to be parsed
    const content = strList.slice(dataset['title'] ? 1 : 0).join('\n');

    return Aqua.code.highlight(content, dataset);
  },
}
Server-side usage | With title and lineStart parsing
Toggle
NumberingCopy
import Aqua from '@ignatiusmb/aqua';
const options = {
  highlight: (str, language) => {
    const strList = str.split('\n');
    const dataset = { language };

    if (strList[0][0] === '~') {
      const [title, lineNumber] = strList[0].split('#');
      dataset['title'] = title.slice(1);
      // Check if there's a hash '#' in the title and use it as start line number
      if (lineNumber) dataset['lineStart'] = +lineNumber;
    }
    const content = strList.slice(dataset['title'] ? 1 : 0).join('\n');

    return Aqua.code.highlight(content, dataset);
  },
}

Examples 

Toggle
NumberingCopy
<div class="card">
  <div class="aqua-form-card aqua-form-wave aqua-form-slide">
    <div class="slide-container sign-up">
      <form class="aqua-form" action="#">
        <h1>Create Account</h1>
        <input type="text" placeholder="Full Name" />
        <input type="email" placeholder="Email" />
        <input type="date" placeholder="Date of Birth" />
        <input type="tel" placeholder="Phone Number" />
        <input type="password" placeholder="Password" />
        <input type="password" placeholder="Re-type Password" />
        <button>Sign Up</button>
      </form>
    </div>
    <div class="slide-container sign-in">
      <form class="aqua-form" action="#">
        <h1>Sign In</h1>
        <input type="email" placeholder="Email" />
        <input type="password" placeholder="Password" />
        <a href="." on:click|preventDefault>Forgot your password?</a>
        <button>Sign In</button>
      </form>
    </div>
    <div class="form-overlay">
      <div class="overlay">
        <div class="overlay-panel left">
          <h1>Welcome Back!</h1>
          <p>Login with your account to keep connected with us</p>
          <button class="ghost white" id="sign-in">Sign In</button>
        </div>
        <div class="overlay-panel right">
          <h1>Join Us!</h1>
          <p>Enter your personal details and start a journey with us</p>
          <button class="ghost white" id="sign-up">Sign Up</button>
        </div>
      </div>
    </div>
  </div>
</div>