https://github.com/timescale/docs.timescale.com-content

Content pages for TimescaleDB documentation
https://github.com/timescale/docs.timescale.com-content

Last synced: 8 months ago
JSON representation

Content pages for TimescaleDB documentation

• Host: GitHub
• URL: https://github.com/timescale/docs.timescale.com-content
• Owner: timescale
• Created: 2018-07-19T19:14:52.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2025-01-13T17:35:45.000Z (12 months ago)
• Last Synced: 2025-05-07T04:58:56.543Z (8 months ago)
• Language: JavaScript
• Homepage: https://docs.timescale.com
• Size: 2.51 MB
• Stars: 42
• Watchers: 14
• Forks: 52
• Open Issues: 40
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# README #

***THIS REPOSITORY IS DEPRECATED. FOR DOCS CHANGES, USE https://github.com/timescale/docs INSTEAD***

This is the source for content for docs.timescale.com.

The docs site uses this repo as a submodule and converts the files directly into

pages using a bash script and markdown parser.

All files are written in standard markdown.

## Contributing

We welcome and appreciate any help the community can provide to make

TimescaleDB's documentation better!

You can help either by opening an

[issue](https://github.com/timescale/docs.timescale.com-content/issues) with

any suggestions or bug reports, or by forking this repository, making your own

contribution, and submitting a pull request.

Before we accept any contributions, Timescale contributors need to

sign the [Contributor License Agreement](https://cla-assistant.io/timescale/docs.timescale.com-content) (CLA).

By signing a CLA, we can ensure that the community is free and confident in its

ability to use your contributions.

## Docs versions

There is a version of the docs for each supported version of the database, stored in

a separate git branch.  Our docs site parses those branches to allow users to choose

what version of the docs they want to see.  When submitting pull requests, you should determine

what versions of the docs your changes will apply to and attach a label to the pull request

that denotes the earliest version that your changes should apply to (`0.9`, `0.10`, `1.0`, etc.)

The admin for the docs will use that as a guide when updating version branches.

### A note on page links

None of the internal page links within these files will work on GitHub.  They are designed to function within the code for the documentation site at [docs.timescale.com](http://docs.timescale.com).  All external links should work.

### A note on anchors

If you want to link to a specific part of the page from the docs sidebar, you

need to place a special anchor `[](anchor_name)`.

**Your anchor name must be unique** in order for the highlight scrolling to work properly.

### A note on code blocks

When showing commands being entered from a command line, do not include a

character for the prompt.  Do this:

```bash

some_command

```

instead of this:

```bash

$ some_command

```

or this:

```bash

> some_command

```

Otherwise the code highlighter may be disrupted.

### General formatting conventions

To maintain consistency, please follow these general rules.

1. Make sure to add line breaks to your paragraphs so that your PRs are readable

in the browser.

1. All links should be reference-style links where the link address is at the

bottom of the page.  The only exceptions are links to anchors on the same page

as the link itself.

1. All functions, commands and standalone function arguments (ex. `SELECT`,

`time_bucket`) should be set as inline code within backticks ("\`command\`").

1. Functions should not be written with parentheses unless the function is

being written with arguments within the parentheses.

1. "PostgreSQL" is the way to write the elephant database name, rather than

"Postgres".  "TimescaleDB" refers to the database, "Timescale" refers to the

company.

1. Use single quotes when referring to the object of a user interface action.

For example: Click 'Get started' to proceed with the tutorial.

### Special rules

There are some custom modifications to the markdown parser to allow for special

formatting within the docs.

+ Adding `sss ` to the start of every list item in an ordered list will result in

  a switch to "steps" formatting which is used to denote instructional steps, as

  for a tutorial.

+ Adding `>:TIP: ` to the start of a blockquote (using '>') will create a "tip" callout.

+ Adding `>:WARNING: ` to the start of a blockquote (using '>') will create a "warning" callout.

+ Adding `>:TOPLIST: ` as the first line of a blockquote (using '>') will

create a fixed right-oriented box, useful for a table of contents or list of

functions, etc.  See the FAQ page (faq.md) for an example.

    - The first headline in the toplist will act as the title and will be separated from the remainder of the content stylewise (on the FAQ page, it's the headline "Questions").

    - Everything else acts as a normal blockquote does.

+ Adding a text free link to a header with a text address (Ex. `## Important Header [](indexing)`) will create an anchor icon that links to that header with the hash name of the text.

+ Adding `:FOOTER_LINK: ` to the start of a paragraph(line) will format it as a "footer link".

+ Adding `:DOWNLOAD_LINK: ` to the start of a link will append a 'download link' icon to the end of the link inline.

+ Adding `x.y.z` anywhere in the text will be replaced by the version number of the branch.  Ex. `look at file foo-x.y.z` >> `look at file foo-0.4.2`.

+ Adding `:pg_version:` to text displayed in an installation section (i.e. any page with a filename beginning `installation-`) will display the PostgreSQL version number.  This is primarily to be used for displayed filenames in install instructions that need to be modular based on the version.

+ Designating functions

    + Adding `:community_function:` to a header (for example, in the api section) adds decorator text "community function".

_Make sure to include the space after the formatting command!_

**Warning**: Note the single space required in the special formats before adding

normal text. Adding ':TIP:' or ':WARNING:' to the start of any standard paragraph will

result in non-optimal html.  The characters will end up on the outside of the

paragraph tag.  This is due to the way that the markdown parser interprets

blockquotes with the new modifications.

This will be fixed in future versions if it becomes a big issue, but we don't

anticipate that.

### Editing the API section

There is a specific format for the API section which consists of:

- **Function name** with empty parentheses (if function takes arguments). Ex. `add_dimension()`

- A brief, specific description of the function

- Any warnings necessary

- **Required Arguments**

    - A table with columns for "Name" and "Description"

- **Optional Arguments**

    - A table with columns for "Name" and "Description"

- Any specific instructions about the arguments, including valid types

- **Sample Usage**

    - One or two literal examples of the function being used to demonstrate argument syntax.

See the API file to get an idea.