• What is this repository for?
• How do I get set up?
  • From Terminal
  • From Finder
  • Running with Docker
• Contributing
  • Process
  • Markdown
  • Where are the Markdown files?
  • Inserting images
    • Figures
    • Icons
  • Shortcodes you might insert
    • Tip, note, important, warning
    • accordion
    • Code snippet
    • Code tabs
    • Content tabs
    • Adding Vimeo
    • Adding Youtube
  • Shortcodes you might see, but will not usually insert
    • xref
    • com
    • Include
    • First Steps-specific shortcodes
      • our-use-cases
      • task
      • detailed-information
      • more and moreitem
      • info-frame
  • Deprecated shortcodes
  • Custom Synerise article metadata
  • Modifying JavaScript
  • HTML check
  • Naming branches
• Deploying to stage
• Versioning
• Troubleshooting
• index.json
• DEPRECATED link check

What is this repository for?

This repository stores the source content for https://help.synerise.com/ (https://hub.synerise.com)

Our Help Center is generated with Hugo (https://gohugo.io/)

How do I get set up?

1. Clone the repository to your local drive.
2. If you're running a system other than MacOS, install this Hugo release (get the extended version): https://github.com/gohugoio/hugo/releases/tag/v0.97.3

From Terminal

3. Open a command line tool.
4. Change the directory to the repo's home directory.
5. Run ./hugo server or ./hugo-m1 server if you use MacBook with M1 processor or newer (or ./hugo server -D if you want to see drafts)
6. Check your content at http://localhost:1313/
   REMEMBER: If you already have Hugo running in another Terminal window, the second server will have a different address. Keep an eye on the Terminal output to find that address.
7. To exit Hugo, press CTRL+C while at the Terminal.

From Finder

1. Open the main folder of the repository.
2. Double click startHugoLocalServer.command
3. Check your content at http://localhost:1313/
   REMEMBER: If you already have Hugo running in another Terminal window, the second server will have a different address. Keep an eye on the Terminal output to find that address.

Running with Docker

This is not the standard way, but if you're interested, I assume you have a reason.

1. In the Terminal, open the main folder of the repository.
2. Enter docker build -t synerise-user-docs . (with the dot).
3. Wait until it builds (may take some time).
4. Enter docker run -p 80:8080 synerise-user-docs
5. Go to localhost:80 and there it is. When running from Docker, the live preview DOES NOT WORK. Any changes you make will only be visible after you build the image again.

Contributing

Process

1. Clone the repository to your machine.
2. Switch to the master branch.
3. Pull from origin/master to local/master (just do git pull) to make sure that the branch you want to create for your work is not created from an older branch.
4. Create a branch to work on, from master (you cannot commit to master).
   Tip: If you're not confident with created branches locally, create one in Gitlab and then switch to it on your local machine.
5. Work on your branch.
6. Monitor your changes locally.
7. Run the HTML tester.
8. Push your changes to Gitlab.
9. Create a Merge Request.
10. Check Gitlab CI/CD to see if your build passed.
11. Optional: deploy your branch to stage.
12. Get reviews.
13. Get approval from Dominika Adamek or Marcin Misiak.
14. Merge when approved.
15. Ask Dominika or Marcin to create a tag and deploy to production.
    The tags can't include the letter v at the beginning (they could before Aug 14, 2025)

Markdown

Markdown is the basis of our articles. The one functionality we usually do not use is images, which are inserted as raw HTML. Occasionally, we also use raw HTML to insert tables, but try to avoid that.

Note that Markdown is very sensitive to indentation. If you have formatting problems, try moving some spaces around. Contact a tech writer if you're stuck.

Learn Markdown
Note that Gitlab, BBucket, and IDE plugins may interpret Markdown a bit differently than Hugo. You must double-check locally in Hugo.

Where are the Markdown files?

They are in content/en.

Inserting images

Images are usually stored in a _gfx folder on the same level of the hierarchy as the article you're using them in. The exception is that Use Cases store them in all-cases/_gfx for historical reasons.

If you want to use an image that already exists in another article do not make another copy if the image. Insert the one that already exists, wherever it's located.

Figures

A figure is an image with a caption.

Our figures are also numbered. Here's an example of how to insert one:

<figure>
<img src="/developers/android-sdk/_gfx/android-simple-push-expanded.png" alt="Expanded simple push notification" class="medium">
<figcaption>Simple push notification presented on Android 10</figcaption>
</figure>

• by default, the figure is centered. You can use <figure class="left"> and <figure class="right"> to change the alignment.
• In the img element:
  • src is the source of the image.
    • If it's an image from the repo, make it an absolute path (where the "root" catalog is /content/en). The path in the above example is absolute.
    • If it's an image stored somewhere externally, this will be a link to it.
  • alt is the text displayed when the image can't be loaded. This is obligatory and also used by people with disabilities, who have screen readers, so make this sensible.
  • classis the class that defines the size of the displayed image in the text. This is also obligatory. Choose from: small, medium, large, full.
    • If you want your image to not have a delicate gray frame around it, add the no-frame class, like so: class="medium no-frame".
• figcaption is the text shown right under the image.

Icons

To insert an in-line icon, for example to show in the text a button that you want the reader to press, use the following HTML:

<img src="/icons/settings-icon.png" alt="Settings icon" class="icon">

IMPORTANT: store all icons in the /static/icons catalog.

Shortcodes you might insert

Shortcodes are used to insert some elements in Hugo, such as notes or code snippets.

Most of them have an opening tag (such as {{% note %}}) and a closing one, recognized by the slash: {{% /note %}}. Some shortcodes, such as the one used for Vimeo, do not have a closing tag.

Shortcodes have two delimiters that are largely interchangeable: % ({{% note %}}) or <> ({{< note >}}). If you're getting weird formatting after inserting a shortcode, try using the other delimiter. Generally, the difference between those two is how they parse Markdown inside them, but because our docs were largely written before Hugo introduced this feature, we're not fully compliant. This will be fixed, someday.

Hugo has some shortcodes available by default: https://gohugo.io/content-management/shortcodes/

This readme provides information about shortcodes that we added on top of that, and the Hugo default ones that we see used more often.

Tip, note, important, warning

Those are four siblings with the same format, but different meaning and styling.

• Tip is for some action that will make your life a bit easier, a "lifehack".
• Note is for extra info, like a link, or something to take into consideration.
• Important is for something that, if ignored, will cause minor problems or loss of work.
• Warning is for something that, if ignored, will cause large problems, downtime, data loss, etc.

{{% tip %}}
Some text here. Can include regular Markdown or other shortcodes.
{{% /tip %}}

{{% note %}}
Some text here. Can include regular Markdown or other shortcodes.
{{% /note %}}

{{% important %}}
Some text here. Can include regular Markdown or other shortcodes.
{{% /important %}}

{{% warning %}}
Some text here. Can include regular Markdown or other shortcodes.
{{% /warning %}}

accordion

Inserts a "bar" that can be expanded to see the content inside it.

{{< accordion "Text displayed on the bar" >}}
Content inside. Can include regular Markdown or other shortcodes.
{{< /accordion>}}

Code snippet

Stores a snippet of code, must be embedded inside the code-tabs shortcode (explained below). If you want to include a colored snippet without the tabs, use Hugo's regular highlight shortcode.

WARNING Avoid any empty lines in the code. They may break the output.

You must provide a language, even if it's not supported. The tab name (see below) is generated from this.

The options are optional, duuuuh.

{{< snippet lang="LANGUAGE" options="OPTIONS">}}
CODE GOES HERE
{{< /snippet >}}

The options and supported languages are described in the Hugo documentation.

Code tabs

Creates a tab view of a few code snippets that can be selected for viewing.

{{< code-tabs >}}
{{< snippet lang="" >}}
some code
{{< /snippet >}}
{{< snippet lang="" >}}
some code
{{< /snippet >}}
{{< /code-tabs >}}

Content tabs

This is a beta-version shortcode, please do not use it for now without contacting Dominika or Marcin first.

Adding Vimeo

Only the ID of the video is required, e.g.: https://vimeo.com/channels/staffpicks/146022717

Extract the ID from the video’s URL and pass it to the vimeo shortcode:

{{< vimeo 146022717 >}}

Adding Youtube

The youtube shortcode embeds a responsive video player for YouTube videos. Only the ID of the video is required, e.g.: https://www.youtube.com/watch?v=w7Ft2ymGmfc

Copy the YouTube video ID that follows v= in the video’s URL and pass it to the youtube shortcode:

{{< youtube w7Ft2ymGmfc >}}

Shortcodes you might see, but will not usually insert

xref

This shortcode creates a link to an article and dynamically uses the title of that article as the text of the hyperlink. You don't have to use it if you don't like it.

For details, read {{< xref "/docs/settings/tool/firebase" >}}.

com

This shortcode lets you leave a comment not rendered in the HTML output (is not visible in the article nor in the HTML of the page). You can use it for leaving reminders or other remarks on the article.

{{< com >}}
Soon, a new version of this feature will appear. Don't forget to update the list of API key permissions. 
{{< /com >}}

Include

Lets you re-use a piece of Markdown content from another file (or actually a file parsed into a page).

It includes ALL the contents from that file. If you want to make a re-usable fragment (a paragraph, a note, or anything), make a Markdown file in the /reuse folder and link the include to that file.

If the target has a relative link in it, that link will be resolved in relation to the file that called the shortcode. Use this to your advantage.

REMEMBER All re-usable files must be kept incontent/en/reuse.

{{% include "path-to-file" %}}

Re-using larger elements is difficult, because included headings are ignored in the table of contents on the right. If you want headings, put them in the file proper, and split the included content into smaller files.

WARNING If your target file starts with { (say, if you're making a re-usable note), it's going to break Hugo. You can work around this by placing an empty block of metadata at the beginning of the target file (because Hugo actually treats it like a page). Just this will be enough:

---
title:
---
{{% some-shortcode-that-happens-to-be-the-first-line-of-the-file %}}

First Steps-specific shortcodes

First Steps have three kinds of notes that can be used only in that part of the docs. They're used like all other notes, but have their own styling.

our-use-cases

{{< our-use-cases >}}

Discover [our use cases](/use-cases/features/ai/) based on AI!
<br></br>
Thanks to them you will discover many possibilities of our AI module!

{{< /our-use-cases >}}

task

{{< task >}}

Prepare similar recommendations campaign, which will show at least 3 products and max 6, which will contain products from current brand and from WOMAN category. Additionaly you can exclude products bought in the last 30 days

{{< /task >}}

detailed-information

{{< detailed-information >}}

- [Documentation](/docs/analytics/expressions/) of analytics module
- [Analytics Suite](https://developers.synerise.com/AnalyticsSuite/) for more advanced usage of the analytics

{{< /detailed-information >}}

more and moreitem

This shortcode includes tiles for First Steps shown at the end of the article.

The tiles are created by inserting a moreitem shortcode inside more.

The moreitem shortcode takes the following parameters:

• image is the URL of the image on the tile (can be in the repo or in CMS)
• title is the tile of the tile
• description is the description on the tile
• link is the link under Learn more on the tile

Example

{{% more %}}
{{% moreitem image="/first-steps/campaigns/_gfx/campaign-confi.png" description="Get to know how to use available features step by step" title="First steps" link="/docs/automation" %}}
{{% moreitem image="https://upload.snrcdn.net/9bbb7035ecf3565cceed63d321d7d9b31236850d/default/origin/d8c3a44e603f456f8c2577d9826eb51d.jpg" description="Get to know how to use available features step by step" title="Use cases" link="/docs/automation" %}}
{{% moreitem image="https://upload.snrcdn.net/9bbb7035ecf3565cceed63d321d7d9b31236850d/default/origin/30608d2496094130aab7f09594cc32ea.jpg" description="Get to know how to use available features step by step" title="User Guide" link="/docs/automation" %}}
{{% /more %}}

becomes this:

info-frame

A frame with additional information. It has an icon, a title, a link, and a description.

IMPORTANT: The icon must be in the /static/icons/first-steps folder. Don't provide the full path in the params, only the icon name.

{{% info-frame title="I am the title" icon="close-l.svg" link="/docs/automation" %}}
Lorem ipsum bekon I am the text.
{{% /info-frame %}}

Deprecated shortcodes

If you take a deep dive into our Hugo backend, you'll find more shortcodes. The ones I did not describe above are deprecated, or not recommended for use for some other reason.

Custom Synerise article metadata

Metadata is a piece of YAML-format info in the beginning of a Markdown file:

title: Lorem ipsum
someOtherMeta: Dolor amet

It includes extra information. If a piece of meta is not required, you don't need to add it at all. Some have default values for that case, as explained in the table.

When it comes to the use-case-specific meta (snrChallenges, snrModule, snrDifficulty, snrTags, snrIndustry, snrChannel), they have a strict list of allowed (case-sensitive) values. To add new values, contact a tech writer. Want to see the list of allowed values? Go to themes/layouts/partials/use-cases/search-meta.html

Name	Required?	Description	Format
title	yes	Title of the article. Shown in menus, on tiles, etc.	string
titleAlt	no	Alternative title displayed on tab name and in previews, for example on Twitter	string
snrUuid	yes	Unique UUID for our search catalog. Once added, this must never change. You can generate UUIDs at https://www.uuidgenerator.net/api/version4/	string
description	yes	A short summary of the article. DO NOT just paste the title here. This is shown in some menus, search results, etc.	string
weight	no	Used to order articles in menus. Lower weight = first in menu. Do not add 1,2,3, etc. Go for 10,20,30, so if you add an article in the future, there is space between the existing ones without changing the weight of everything that follows.	integer
draft	no	IS BORKEN NO USE If true, the article is only visible in draft mode. Defaults to false	boolean
snrExcludeFromSearch	no	If true, this article will not be shown in the search results. Defaults to false.	boolean
snrNoTreeOnLeft	no	If true, the article will not have the menu on the left side. Defaults to false	boolean
bookshowtoc	no	If false, the table of contents on the right is not shown. Defaults to true	boolean
snrChallenges	yes, in use cases	A list of challenges applicable to this use case. See, modify, add, or remove allowed values in /themes/book/layouts/partials/use-cases/search-meta.html.	array of strings
snrModule	yes, in use cases	A list of modules (from the Synerise application) applicable to this use case. See, modify, add, or remove allowed values and module icons in /data/moduleIcons.yml.	array of strings
snrDifficulty	yes, in use cases	The difficulty of the use case. See, modify, add, or remove allowed values in /themes/book/layouts/partials/use-cases/search-meta.html.	array of strings (one item)
snrTags	yes, in use cases	A list of tags applicable to this use case. See, modify, add, or remove allowed values in /themes/book/layouts/partials/use-cases/search-meta.html.	array of strings
snrIndustry	yes, in use cases	A list of industries applicable to this use case. See, modify, add, or remove allowed values in /themes/book/layouts/partials/use-cases/search-meta.html.	array of strings
snrChannel	yes, in use cases	A list of channels applicable to this use case. See, modify, add, or remove allowed values in /themes/book/layouts/partials/use-cases/search-meta.html.	array of strings
snrUtcTimezonePublishDate	yes, in use cases	Date when the Use Case becomes available on prod IN UTC TIME ZONE. Needed for sorting by publish date and promoting new articles. The approximate time between creating a tag and actually deploying to prod is 5-10 minutes + up to 25 more before it's indexed by the AI and shown on the list of cases (but it's accessible through a link before the index is re-built). Format: 2022-06-24T12:00:00Z	string (ISO 8601)
snrClientLogos	no	A list of clients whose logos will be shown with a use case. The client "yes" must be entered with quotation marks, otherwise YAML treats it as a special keyword and that causes an error. The list of available clients and their logos is stored in /data/clientLogos.yml. If you want to change the image of a logo, you only need to update the URL in this one file and all the cases which name this client will receive the new logo.	array of strings
snrPartnerLogos	no	A list of partners whose logos will be shown with a use case. The list of available partners and their logos is stored in /data/partnerLogos.yml. If you want to change the image of a logo, you only need to update the URL in this one file and all the cases which name this partner will receive the new logo.
menu	no	Deprecated, do not use	object
tags	no	Deprecated, do not use	array

TIP An array of strings may be written in two ways in the metadata. Example with snrModules:

snrModule: [Communication,Automation]

or

snrModule:
  - Communication
  - Automation

Modifying JavaScript

If you want to change JS code:

1. go to themes/book/static/ and find the JS there.
2. Make your changes.
3. Do npm run webpack to rebuild* the JS files.
4. Commit the changes, including the files changed by webpack.

Considerations:

1. DO NOT change JS directly in the static/js folder. Your changes might work locally, but the files here are re-built during Docker build in GitLab.

2. *Our webpack is quite old and has SSL compatibility issues with MacOS (Intel and Silicon). To run locally, you can try one of these:

   •  export NODE_OPTIONS=--openssl-legacy-provider
      npm run webpack
     

   • Use node version 16

3. Some article templates have JS embedded in the directly instead of in separate JS files.

HTML check

The HTML check runs at every build and checks:

• correctness of internal links
• correctness of external links
• links to headings (anchors)
• images (in repo and external)
• the existence of "alt" attributes

The check may take up to a few minutes to run on your local machine, but it has a cache that usually makes it much faster.

You can run HTML check locally in on those ways:

• In Finder, in the repo's root folder, double-click:
  • For MacBooks with Intel processor (older): ./htmltest-intel.command
  • For MacBooks with M1 processor (newer): ./htmltest-m1.command
• In the terminal, in the repo's root folder, enter:
  • For MacBooks with Intel processor (older): ./htmltest-intel.command
  • For MacBooks with M1 processor (newer): ./htmltest-m1.command

TIP: If you're not sure which processor you have, run any of those scripts. If it says ./htmltest-m1.command:13: bad CPU type in executable: tmp/htmltest at the end of the output, try the other one ;)

Naming branches

DO:

• use numbers and letters (0-9, a-z, A-Z)
• you can use - as a space, it's the only one special character allowed

DONT:

• don't use special characters, such as !@#$%^&*()[]{}<>,.?/\
• don't use camel case (for example, CaseLandingPage)
• don't use more than one pause (-) in a row, for example, Use-Case---LP

Examples of branch names:

• DOC-899 (a branch which contains changes requested in the Jira task DOC-899), this has the extra benefit of linking the branch to Jira automatically
• forms-landing-page
• hot-fix-segmentation
• my-first-merge2
• distinctfilters

Deploying to stage

The pages are deployed to http://help.NS-NAME.snrstage.com, where NS-NAME is for example mmisiak2 (not devns-d-mmisiak2-dev - this may change at anytime though).

Do not deploy to someone's personal namespace unless you've verified with that person.

Deploys are from last successful build on the selected branch.

1. After pushing, make sure the build on your branch was successful
   (the pipelines list does NOT update live when a build completes and may show it as in progress for a longer time, click the job's details and check the console, maybe it's actually completed already).
2. Go to Build > Pipelines > Run pipeline.
   
3. From the dropdown, select the branch you want to deploy from:
   
4. Enter the variables:
   TIP: If the variables don't load, try refreshing the page a few times. GitLab's a bit bugged here. You can also add variables manually if refreshing doesn't help.
   • set deploy_on_demand to true
   • from the deploy_namespace list, select the namespace where you want to deploy.
5. Click Run pipeline.

In the page that opens, you can see the progress of your pipeline. The k8s-deploy-on-demand stage is where you can monitor the progress of the deploy. In short, it's Gitlab doing a simplified stevedore deploy for you.

The pipeline usually takes a few minutes to complete and push the changes to the staging website (after the pipeline completes, about 1-2 more minutes).

Versioning

Tag names are vX.Y.Z

• X increases for huge changes, like a completely new graphical layout or a total re-structuring of the content.
• Y increases for major changes such as an article being added, deleted, or moved, numerous images changing, an important visible change in the UI.
• Z increases for minor changes, such as typos, adding a paragraph somewhere, or technical tasks (invisible to readers of the help) such as changing the readme, cleaning up images that are not used anywhere.

Troubleshooting

• Search and tracker do not work locally or on stage environments. This is normal behavior.
• Markdown is sensitive to spaces, line breaks, and indentation in the source. If your output is formatted wrong, this is often the reason.
• If Hugo doesn't refresh your content live, restart it. The mechanism is not perfect.
• If you get a message about unverified developer when starting Hugo:
  1. Close that message.
  2. Go to System Preferences > Security and Privacy > General
  3. Find the message about Hugo being blocked and click the option to allow anyway.
  4. Start Hugo again and allow it to run. You should not be asked again on this machine.
• If you get this panic error:

  Marcins-MacBook-Pro-2:synerise-user-docs marcinmisiak$ ./hugo server
  Building sites … panic: runtime error: invalid memory address or nil pointer dereference
  [signal SIGSEGV: segmentation violation code=0x1 addr=0x20 pc=0x4bed652]
  
  goroutine 137 [running]:
  github.com/gohugoio/hugo/hugolib.(*shortcodeHandler).extractShortcode(0xc0176b3840, 0x5, 0x0, 0xc0177007b0, 0x3, 0x4, 0x557b4a0)
        /root/project/hugo/hugolib/shortcode.go:505 +0x882
  [...]
  

  We have seen two possible reasons so far: an unclosed shortcode or a duplicate closing tag in a shortcode.
  Look through your diff and find where it happened.
• Errors caused by our own custom templates usually contain instructions on what to do. Read the build log in the console and you should know how to proceed.

index.json

There is an index used by the Synerise Web Application to assign help pages to different views. It's maintained by the frontend developers and located in /content/en/docs/index.json.

DEPRECATED link check

THOSE LINK CHECKS ARE REPLACED BY HTMLTEST (see above). We use it occasionally, so it stayed here so the information isn't lost.

https://gitlab.synerise.com/core/synerise-user-docs-lc/pipelines

1. Verify that the build of your merge into master is finished and deployed to RC: https://gitlab.synerise.com/core/synerise-user-docs/pipelines
2. If the build is complete, go to https://gitlab.synerise.com/core/synerise-user-docs-lc/pipelines
3. Click "Run Pipeline".
4. In the Input variable key field, enter URL (case sensitive!).
5. In the Input variable variable field, enter https://help.jsons.snrstage.com/ (or even better, deploy to some other space before merging to master and deploying to jsons).
6. Click Run pipeline.
7. Open the pipeline's progress and check the results (it can take about 15 minutes to finish).

You can run this on demand for any other URL.