Welcome to the source repo for Logz.io Docs!
Our site is built on Jekyll.
We merge the
develop branch as needed.
Docs are released to docs.logz.io from
- Changes and pull requests
- Working in Markdown
- Credits and contributors
Please follow the Setup instructions so you can start.
Make all pull requests to the
If you just want to submit a quick edit suggestion, you can open an issue.
Please preview your changes locally before submitting pull requests.
What pull requests we can't merge
We need to reject any pull requests that include these changes:
- Changes to our OpenAPI file
- Changes to our config file
- Changes to another contributor's information
If you want to suggest a change or report an error in any of these files, please open an issue.
Please note we reserve the right to decline or change a pull request for any reason.
Please review the Logz.io Community Code of Conduct
If you haven't contributed to logz-docs before, follow these steps to get started.
Join GitHub if you don't already have an account.
macOS: Xcode command line tools:
RVM with Ruby:
curl -sSL https://get.rvm.io | bash -s stable --ruby
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
sudo gem install bundler
Fork the logz-docs repository
Clone your fork, checkout the
developbranch, and add logzio/logz-docs as your upstream repo:
git clone https://github.com/<your_github>/logz-docs.git cd logz-docs git checkout develop git remote add upstream https://github.com/logzio/logz-docs.git git fetch upstream
sudo gem install bundler jekyll
Install logz-docs Ruby gems:
sudo bundle install
Changes and pull requests
develop as the main branch.
Our site is automatically deployed when we merge
For you, this means that you should create new branches from
develop and make your changes there.
You should also regularly sync your fork with the upstream repo (logzio/logz-docs) so that we can merge your changes without any problems.
So the ideal process looks a little like this:
Syncing your fork
Keeping your fork up to date allows us to easily merge your changes. This is a pretty simple process.
To sync your fork:
Open a terminal window and
cdinto your logz-docs folder.
Checkout your local develop branch, pull the logzio/logz-docs
developbranch, and push the updates to your fork:
git checkout develop git pull upstream develop git push
Before submitting pull requests, preview your changes locally. This does a few things to help you catch mistakes:
- Seeing the formatted text, outside of a text editor and without all the markup, gives you a fresh look at your content.
- You can be sure that your Markdown is formatted correctly and converts to HTML just as you meant it to.
We ask that you check your work for errors and readability.
To preview locally:
Point your browser to http://localhost:4000/. (Don't worry about the ducks. They're just there to tell you this is a local preview and not on the web.)
Making your first pull request
We like to give contributors credit for their work, so go ahead and add yourself as a contributor in your first pull request.
To add yourself as a contributor:
Find the contributors folder on your machine at
logz-docs/_source/logzio_collections/_contributors. Add a new Markdown file, named
So if your GitHub username is agrant, your file is named
agrant.md. This is your identifier when you contribute to docs.
Copy this YAML content to the file, and add your information. If something doesn't apply to you, delete the line that doesn't apply:
--- title: <your name> website: <your website url> linkedin: <your linkedin username> twitter: <your twitter handle> github: <your github username> ---
Don't add any other content to the file.
Save and commit.
Include this file in your first pull request. If you're authoring a file, add your identifier (GitHub username) to the
So if your username is chaostheory, you'll add
- chaostheoryto the file's
Working in Markdown
Logz.io docs use kramdown-flavored Markdown. Where possible, avoid HTML tags.
- Leave a blank line between text blocks.
- Indents are two spaces (not tabs). To nest blocks in a list, indent twice (four spaces). This keeps nested items from breaking a list.
- You can put Markdown formatting in an HTML container, but please preview your code locally to make sure nothing unexpected is happening with the HTML conversion.
#####(h2 through h5) for normal headings.
######(h6) to introduce procedures and how-tos.
- Our template reserves
#(h1) for page titles. Don't use.
- We don't have a strict style for procedures, except to make them as simple as possible.
- Avoid long procedures. If your procedure has more than 10 steps, shorten it, or break it apart into multiple procedures.
- You can use ordered and unordered lists in procedures. Lists can be nested two levels deep.
- Nest other blocks in the second level by indenting the block another level. This keeps nested blocks from breaking lists.
Info boxes need a
<div class="info-box"> container.
Info boxes come in three CSS classes:
CSS handles the styling and adds a header.
Indent content on its own lines between the
<div class="info-box note"> Notes are generally non-actionable. They’re more important than the surrounding text but less important than warnings. Could something bad happen if the user ignores this? If no, then it’s a note. Otherwise, it’s an important note. </div>
<div class="info-box tip"> Pro tips convey best practices and good actions to ensure success. Think of these as more proactive than important notes. </div>
<div class="info-box important"> Important notes help the user work through common trip-up points. If the user could cause damage by ignoring the important note, consider a warning instead. </div>
<div class="info-box warning"> Use warnings when the user could cause damage that’s difficult or impossible to recover from. If you need something less severe than a warning, consider an important note or a note. </div>
Surround inline code samples with a single backtick:
Jekyll supports syntax highlighting for code blocks if you say what the code actually is.
For example, for HTML:
```html <i class="fas fa-dove"></i> <div class="info-box note"> This is a note. </div> ```
Credits and contributors
We invite contributions to docs, and we maintain a list of contributors at the Logz.io Docs site.