ACE - HTML Awesome Code Element

ACE is a JS modules which offers both HTML and JS APIs to integrate code samples in web pages and various documentations systems.
Supports syntax highlighting, compilation, and execution of a wide range of programming languages.

---

Showcases (CI-deployed)

showcase name	status
🌐 <ace-cs>	✔️
🌐<div> placeholders	✔️
🌐 acs miscs	✔️
🔌 Doxygen integration (plain)	✔️
🔌 Doxygen integration with Doxgen-awesome-css	❌ (incoming)
🕹️ Interactive live demo	✔️

---

How does it work ?

Internaly, ace-cs module uses the compiler-explorer API for languages supports, code compilation and execution.

• See supported languages
• See supported compilers

Such code-sections behaviors and styles are highly customizables (supports themes, dark-mode, styles/layouts, etc.).

Content

CodeSection

Ths is the module's main components. It represents a code example, which can optionally be executed. If so, its associated output is then displayed on another side panel.

HTML API

<ace-cs language="cpp" toggle_execution="true">
#include <iostream>
auto main() -> int {
    auto i = 42;
    std::cout << "some console output : " << i;
    return i;
}                       
</ace-cs>

Note that users do not have to care about invalid HTML in the provided code. For instance, in the example above, <iostream> does not generates invalid HTML, neither shift operators <<.

Javascript API

let code = `
#include <iostream>
auto main() -> int {
    std::cout << 'Hello, there';~
    return 42;
}
`
let code_section = new CodeSection(code, 'cpp')
    // equivalent to:  awesome_doc_code_sections.HTMLElements.CodeSection
// attach `code_section` to the DOM ...

Which is equivalent to the following plain HTML:

• As div

  <div class='awesome-doc-code-sections_basic-code-section' language="cpp">
  <pre><code>
  #include &lt;iostream&gt;
  auto main() -> int {
      std::cout << 'Hello, there';
      return 42;
  }
  </code></pre>
  </div>

• As custom awesome-doc-code-sections_code-section HTMLElement

  <awesome-doc-code-sections_code-section language="cpp">
  #include &lt;iostream&gt;
  auto main() -> int {
      std::cout << 'Hello, there';
      return 42;
  }
  </awesome-doc-code-sections_code-section>

• As custom awesome-doc-code-sections_code-section HTMLElement (formated)

  <awesome-doc-code-sections_code-section language="cpp">
  <pre><code>
  #include &lt;iostream&gt;
  auto main() -> int {
      std::cout << 'Hello, there';
      return 42;
  }
  </code></pre>
  </awesome-doc-code-sections_code-section>

• As custom awesome-doc-code-sections_code-section HTMLElement (using 'code' attribute)

  <awesome-doc-code-sections_code-section language="cpp" code="#include <iostream>
  auto main() -> int {
      std::cout << 'Hello, there';
      return 42;
  }">
  </awesome-doc-code-sections_code-section>

Note that creating an empty CodeSection/code-section is not recommanded on the user-side.
Internally, it creates a shadow-root slot, which associated with an event listener will wait for some content to be added. Once done, the shadow-root is removed, and the element cleaned-up.

The main scenario for such usage is defered initialization, for instance when polling some code from an API.
Even though, users might prefer to wait for such API response, and only once received then create the CodeSection element and attach it to the DOM.

Toggle dark/light mode

<button is="awesome-doc-code-sections_toggle-dark-mode-button"></button>

Theme selector

Users can experiment which theme they prefer using highlightjs.org static demo.

Such stylesheets are imported from cndjs, so the following pattern must match a valid url : https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/${theme_name}.js, where ${theme_name} is a valid theme name.

Note that the first option is the default one here.

<!-- The default one is the first one -->
<select is="theme-selector">
    <option value="tokyo-night"></option>
    <option value="base16/google"></option>
</select>

---

Special thanks

  for his kind CSS reviews & mentoring

And to all contributors :

Made with contrib.rocks.