Writing Documentation

The documentation of the SDK is written in HTML and uses Jekyll and Github pages to publish the web site.

Setting up the local environment (MacOS)

First, install Ruby. Do not use the default ruby install and setup a proper ruby env using chruby and ruby-install

brew install chruby ruby-install
ruby-install ruby

# You may have to start a new terminal for the following to work

echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.bash_profile
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.bash_profile
echo "chruby ruby-3.1.2" >> ~/.bash_profile # run 'chruby' to see actual version

ruby -v

Then install bundler, a dependency manager for Ruby.

gem install bundler

Test the documentation site. Everything is available in the docs folder

cd docs
bundle install
bundle exec jekyll serve 

# visit it at http://127.0.0.1:4000

Add a page

To add a documentation page, you first need to add the page to the navigation menu. The menu is defined as a yaml file in docs/_data/navigation.yml.

Edit this file and add your entry where you want. Make sure it is in the right section, the SDK documentation, or the Campaign documentation or advanced topics. Each entry has a name, which will be displayed in the navigation menu, and the corresponding link to an html page containing the documentation.

- name: Troubleshooting
  link: troubleshooting.html
- name: --
- name: Documentation
  link: documentation.html
  children:
    - name: Connecting to Campaign
      link: connecting.html
    - name: My new page
      link: myPage.html
    - name: Concepts
      link: concepts.html

Adding page menu in the SDK documentation

Now you can create the HTML file for the page. Make sure you set the layout to page and give an appropriate title in the file header (called the Jekyll front matter)

  ---
  layout: page
  title: My new page
  ---
  <p>Hello, I'm a new page</p>

CSS reference

A very simple CSS is used, defined in assets/css/styles.css

Headers

Use the <h1> and <h2> elements for titles. Documentation pages should be short, and you should not use deeply nested headers

<h1>I'm a H1 header</h1>  
<h2>I'm a H2 header</h2>  

Paragraphs

• Use the <p> element for all text paragraph
• Use the info class to format a paragraph as an information notice
• Use the warning class to format a paragraph as an warning notice
• Use the caption class to format a paragraph as a caption to an image or a code block
• Use the ref class to format a paragraph as reference to another part of the documentation or an external site

<p>I'm a simple paragraph with no additional CSS class</p>  
<p class="info">I'm an information notice</p>  
<p class="warning">I'm an warning notice</p>  
<p class="caption">I'm a caption notice</p>  
<p class="ref">I'm a reference to the <a href="https://github.com/adobe/acc-js-sdk">ACC JS SDK</a></p>

Code snippets

Use the <pre class="code"> element to display code, scripts, etc.

<pre class="code">
const greetings = "Hello, world";
console.log(greetings);
</pre>

const greetings = "Hello, world";
console.log(greetings);

Emphasis

• Use the <b> element to emphasis text in paragraphs
• Use the <span class="emphasis"> element to highlight a particular section of code in a <pre block
• Use the <span class="comment"> element to darken a particular section of code in a <pre block (like a comment)

<p>I'm a simple paragraph with an <b>important</b> word</p>  

<pre class="code">
  const greetings = "I'm a code block with <span class="emphasis">important</span> text";
  console.log(greetings);
</pre>
<pre class="code">
  const greetings = "Hello, world"; <span class="comment">// I'm a comment</span>
  console.log(greetings);
</pre>

const greetings = "I'm a code block with important text";
console.log(greetings);

const greetings = "Hello, world"; // I'm a comment
console.log(greetings);