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.
showcase name | status |
---|---|
🌐 <ace-cs> | ✔️ |
🌐<div> placeholders | ✔️ |
🌐 acs miscs | ✔️ |
🔌 Doxygen integration (plain) | ✔️ |
🔌 Doxygen integration with Doxgen-awesome-css | ❌ (incoming) |
🕹️ Interactive live demo | ✔️ |
Internaly, ace-cs module uses the compiler-explorer API for languages supports, code compilation and execution.
Such code-sections behaviors and styles are highly customizables (supports themes, dark-mode, styles/layouts, etc.).
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.
<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 <<
.
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 <iostream> 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 <iostream> 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 <iostream> 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.
<button is="awesome-doc-code-sections_toggle-dark-mode-button"></button>
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>
And to all contributors :
Made with contrib.rocks.