Skip to content

Documentation Convention

Our team uses this public documentation to build our products. It serves as a single source of truth to ensure consistent implementation across different platforms. We strive to adhere to consistent principles to maintain a coherent structure. Work on the convention is still ongoing.

Check before publishing

Documentation is published automatically when merged into the main branch. Therefore, before merging a pull request, please check locally

  • ZERO Warning policy  (1)
  • the documentation is easy to read
  • it adheres to accepted conventions
  • you like it

  1. Strict mode

    MKDocs configuration has strict parameter set to true. This will cause MkDocs to abort the build on any warnings.
How to set up a local preview?

To build and preview the documentation locally, you'll need to install Material for MKDocs along with the required plugins:

pip install \
  mkdocs-material \
  mkdocs-minify-plugin \
  mkdocs-include-markdown-plugin \
  mkdocs-exclude-search \
  mkdocs-macros-plugin \
  mkdocs-redirects \
  requests

Once everything is installed, navigate to the root of your docs repository clone and run

mkdocs serve

Strict mode

MKDocs configuration has strict parameter set to true. This will cause MkDocs to abort the build on any warnings. If you need to temporarily bypass this, run mkdocs serve --no-strict

You should see output like

INFO    -  [10:46:26] Serving on http://127.0.0.1:8000/

Open that URL in your browser to view the documentation.

API rate limit exceeded

If you see <version> instead of actual SDK version numbers, the GitHub API may have rejected request due to rate limiting.

To fix this, generate a GitHub Personal Access Token and authorize your requests:

  1. Go to https://github.com/settings/tokens.
  2. Click "Generate new token (classic)".
  3. Fill in the following:
  4. Note: Docs GitHub API Access
  5. Scopes:
    • ✅ public_repo if you're accessing only public repositories, or
    • ✅ repo if you're accessing private ones
  6. Copy the generated token ghp_... — it will be shown only once.

Then, in your terminal:

export GITHUB_TOKEN=ghp_your_token_here
mkdocs serve

This will authorize your GitHub API requests and avoid the default 60-requests-per-hour limit.

External

New tab/window

Always add 

{:target="_blank"}
for an external link to open it in a new tab or window

Visual mark

Always visually mark links that lead outside the documentation site. There are two options:

Add this icon to the end of the link title

:octicons-link-external-24:

Example

[aiuta.com :octicons-link-external-24:](https://aiuta.com){:target="_blank"}

aiuta.com

When grouping links into blocks with grid cards you can omit the icon if you use an explicit action in the link title, such as "Open", "Download", etc.

Example

<div class="grid cards" markdown>

- :fontawesome-brands-google-play: [Get it on __Google Play__](https://play.google.com/store/apps/details?id=com.aiuta.fashionsdk.demo){:target="_blank"}
- :fontawesome-brands-shopify: [View in the __Shopify__ app store](https://shopify.aiuta.com){:target="_blank"}

</div>

Internal

This leads to the same result but is easier to maintain in the future.

Root is /docs

[About SDK](/sdk/index.md)

![img](/media/about.png){ width=100 }
About SDK

img 

[About SDK](../../sdk/index.md)

![img](../../media/about.png){ width=100 }
About SDK

img

Custom doc admonition

If you want to specifically highlight links as references to other parts of the documentation, use a custom doc admonition that has some special style settings

Example

!!! doc "To understand this, see [that](#)"

To understand this, see that

Example

!!! doc "For full context, see"

    - [this](#)
    - maybe [that](#)
    - and something [more](#)

For full context, see

Sources

Always provide links to sources and packages, if available, giving preference to grid cards .

Example

<div class="grid cards" markdown>

- :fontawesome-brands-flutter: [Pub.dev package :octicons-link-external-24:](https://pub.dev/packages/aiuta_flutter){:target="_blank"}
- :fontawesome-brands-github: [Plugin sources :octicons-link-external-24:](https://github.com/aiuta-com/flutter-sdk){:target="_blank"}

</div>

Code blocks

Instead of comments, give preference to annotations , which can be much more detailed and contain active links, images, and instructions. Describe things in detail, keeping the code clean and free of comments. Don't forget to specify default values in the example admonition , if applicable.

Example

``` typescript
Foo {
  bar: Bar // (1)!
}
```

1.  Here is annotaion with [link](#), image

    ![image](/media/images/imagePickerSample1.png){ width=50 }

    !!! example ""
        and default value


Foo {
  bar: Bar // (1)!
}

  1. Here is annotaion with link, image

    image

    and default value

Schemes

To describe a language-independent scheme or data model use a code block with typescript highlighting where

  • omit key constructs such as class, new, etc., that are redundant for the description
  • avoid traling commas and semicolons, as well as colons between property definitions and opening brackets, cluttering up the scheme
  • prefer PascalCase for types and camelCase for properties (1)
  • define collections as List<> and Map<>
  • denote enumerated / sealed types with |, combined with tabs for their schemes
  • indicate optional fields with | null
  • indent with 2 spaces
  1. except for the API, which uses snake_case

Example

``` typescript
Foo {
  fooProperty1: String
  fooProperty2: Number | null
  fooProperty3: Bar1 | Bar2 | null

  fooEmbeddedeType {
    fooEmbeddedeTypeProperty1: String
  }
}
```

=== "Bar1"
    ``` typescript
    Bar1 {
      bar1Property1: List<Bool>
    }
    ```

=== "Bar2"
    ``` typescript
    Bar2 {
      bar2Property1: Map<String, Bool>
    }
    ```    

Foo {
  fooProperty1: String
  fooProperty2: Number | null
  fooProperty3: Bar1 | Bar2 | null

  fooEmbeddedeType {
    fooEmbeddedeTypeProperty1: String
  }
}


Bar1 {
  bar1Property1: List<Bool>
}

Bar2 {
  bar2Property1: Map<String, Bool>
}

Templates

If several pages of your documentation contain identical sections regarding repetitive reminders, a list of some questions, or system requirements, please create templates and include them with the include-markdown plugin

Example

Remove spaces in { % % }. Careful, it works inside code blocks also.

{ % include-markdown "sdk/templates/flutter/requirements.md" % }


sdk: >=3.1.0 <4.0.0
flutter: >= 3.19.6

include macros

The macros plugin also provides its own include with the same syntax, but in the case of complex pages and nested indents, it often breaks the page layout, whereas include-markdown does not have this issue.

Appearance

Keep documentation clean, uncluttered, divided into sections, use visual indicators to draw attention to specific areas (icons, admonitions, grid cards mentioned earlier).

Dark theme

Let's respect people who prefer dark themes

  • provide a contrasting alternative for monochrome images that cannot be colored, add #only-light or #only-dark at the end of the resource path
  • define a contrasting background with stylesheets/aiuta.css for anything that has no alternative in the dark version

Example

<!-- good in both themes -->

:material-format-color-text:{ .cl-aiuta }
![back24](/media/icons/back24.png#only-light){ width=12 } 
![back24](/media/icons/on-dark/back24.png#only-dark){ width=12 }
![close24](/media/icons/close24.png#only-light){ width=12 } 
![close24](/media/icons/on-dark/close24.png#only-dark){ width=12 }

<!-- bad in a dark theme  -->

:material-format-color-text:{ .cl-selection-background }
![back24](/media/icons/back24.png){ width=12 }
![close24](/media/icons/close24.png){ width=12 }

.cl-aiuta {
  color: #4000FF;
}

/* Light background for dark colors to contrast */
.cl-primary,
.cl-aiuta {
  background-color: #FFFFFF;
  border-radius: 6px;
}

back24 back24 close24 close24

back24 close24

Swich docs to a dark theme using / toggle in the header to see the difference

Custom icons

If you need a special icon, you couldn't find a suitable one among the huge number available icons , and want to export yours from Figma and place it in the overrides/.icons directory, please edit the exported svg file manually, replacing the fill color (usually white or black for icons) with the currentColor to match current typeface color.

Example

<svg width="29" height="29" viewBox="0 0 29 29" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="29" height="29" rx="4" fill="white"/>
</svg>

<svg width="29" height="29" viewBox="0 0 29 29" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="29" height="29" rx="4" fill="currentColor"/>
</svg>

In the current version of Figma, you can set the currentColor as a value but it will unfortunately be replaced with some explicit color, probaly #CCCCCC

How to use custom icons?

Custom icons, which are located in the overrides/.icons directory, will be available to use by putting the valid path between two colons, and replacing / with -

Example

:aiuta-logo: :aiuta-favicon:

Common sense

Use it.