Skip to main content

Tips and Tricks

This article will provide some dos and don'ts and some general information on how to write documentation in Markdown.

Markdown​

A cheat sheet will all the Markdown features can be found here. An overview of Markdown features specific to Docusaurus can be found here.

If you're using Visual Code to write markdown files, install this great extension: Markdown All in One.

Naming convention directories and files​

The order of the articles in the sidebar can be set in two ways:

warning

Using a numeric prefix is discouraged for new articles. When we need to change an article's position, we also need to update all internal links to that article.

faq/some-article.md
- See this [other article](../04-other-article.md)
+ See this [other article](../05-other-article.md)

A file should ALWAYS start with the article title​

The first line of each document should contain a hashtag (#), followed with the title of the article. Documents that don't follow this approach will be rejected!

Example:

# Title of the Article

...
Content
...

Always use backticks when using HTML tags​

When using HTML tags like <p>Some example</p>, <video>,... always surround them with backticks `like this`. Alternatively, you can put a backslash before the opening <, like this: \<p>

If not, Docusaurus will try to interpret it like an HTML tag or React component, which probably won't render correctly.

Example:

`<p>Some example</p>`
\<p>Another example\</p>

You can define a link in Markdown as follows:

[this is a link](path-to-follow)

When linking to another document, use the relative path, including the file extension:

[a relative link](../how-to-guides/01-ads/02-customizing-the-ad-overlay-text.md)

When linking to the API reference, use the absolute path along with the pathname:// protocol:

[ChromelessPlayer](pathname:///theoplayer/v7/api-reference/web/classes/ChromelessPlayer.html#constructor)

When linking to an external page:

[link text](https://www.theoplayer.com)

When using anchor links: the link will look like #title-of-section. Anchor links should always be in lower case!

Example: we want to link to the section which has as title SDKs, and one with title Code Examples:

[Anchor link to SDKs](#sdks)
[Anchor link to Code Examples](#code-examples)

## SDKs

...

## Code Examples

...

You can customize a header's anchor ID by adding {#anchor-name} at the end (documentation). This can be useful if the heading is very long, or if the heading contains special characters.

[Anchor link to connect with custom receiver application](#custom-receiver-app)

## Connect with custom Chromecast Receiver application \{#custom-receiver-app}

...

Using images​

IMPORTANT: the image name should NOT contain any spaces. If not following this rule, the image will not show up in GitHub. Example: my-image.png.

Images can be stored anywhere in the project. Conventionally, we put them in an assets directory.

To insert an image in a document, use the relative path:

An image will be shown below:

![Alt text](../../assets/img/image-15.png)

Rules when inserting code blocks​

When inserting a code block, always specify the language you're using so the code gets highlighted correctly.

  • For Web, use ```js
  • For Android, use ```java
  • For iOS, use ```swift

When you want to show code examples for different SDKs, make use of headings per SDK.

Example

Let's see some code examples for the various SDKs.

### Web SDK

```js
function playingEventHandler(event) {
  var adIsPlaying = player.ads.playing;
  console.log('PLAYING', adIsPlaying ? 'Advertisement' : 'Content', event);
}

player.addEventListener('playing', playingEventHandler);
```

### Android SDK

```java
final EventListener<PlayingEvent> playingEventHandler = new EventListener<PlayingEvent>() {
    @Override
    public void handleEvent(PlayingEvent playingEvent) {
        tpv.getPlayer().getAds().requestPlaying(new RequestCallback<Boolean>() {
            @Override
            public void handleResult(Boolean adIsPlaying) {
                System.out.println("PLAYING " + (adIsPlaying ? "Advertisement" : "Content"));
            }
        });
    }
};
tpv.getPlayer().addEventListener(PlayerEventTypes.PLAYING, playingEventHandler);
```

### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
self.eventListener = self.theoplayer.addEventListener(type: PlayerEventTypes.PLAYING) { [weak self] event in
    self.theoplayer?.ads.requestPlaying() { (result, _) in
        print("player.ads.playing = ", result!)
    }
}
```

Will result in:

Result

Let's see some code examples for the various SDKs.

Web SDK​

function playingEventHandler(event) {
  var adIsPlaying = player.ads.playing;
  console.log('PLAYING', adIsPlaying ? 'Advertisement' : 'Content', event);
}

player.addEventListener('playing', playingEventHandler);

Android SDK​

final EventListener<PlayingEvent> playingEventHandler = new EventListener<PlayingEvent>() {
    @Override
    public void handleEvent(PlayingEvent playingEvent) {
        tpv.getPlayer().getAds().requestPlaying(new RequestCallback<Boolean>() {
            @Override
            public void handleResult(Boolean adIsPlaying) {
                System.out.println("PLAYING " + (adIsPlaying ? "Advertisement" : "Content"));
            }
        });
    }
};
tpv.getPlayer().addEventListener(PlayerEventTypes.PLAYING, playingEventHandler);

iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)​

self.eventListener = self.theoplayer.addEventListener(type: PlayerEventTypes.PLAYING) { [weak self] event in
    self.theoplayer?.ads.requestPlaying() { (result, _) in
        print("player.ads.playing = ", result!)
    }
}