Docs

Table of Contents

1. Installation
2. Relative Path Image Support
3. Challenge Server API Reference
4. Front Matter Reference
5. Usage in Slack
6. Usage in Github Actions
7. Usage in Github PRs

Installation

The FizzBuzz.md cli tool is a zx script, so you'll need to install zx:

brew install zx

Next, download the cli script and add it to your path if you're in to that sort of thing:

curl https://github.com/kmdupr33/fizzbuzz.md/cli.zx/raw

Finally, set the API token you received upon account creation as an environment variable:

# .zshrc
export FBMD_TOKEN=<token>

Relative Path Image Support

Relative image paths are supported. The cli will upload images referenced in your markdown file.

Challenge Server API Reference

The FizzBuzz cli creates a challenge server that provides endpoints:

• for applicants to request to start a challenge
• to render your markdown file
• for applicants to submit questions about a challenge
• for applicants to submit their solutions

POST api/challenges/<id>/applications

Request to start a challenge.

Request body:

{
  "email": "string"
}

Response body:

{
  "token": "string"
}

GET /challenges/<id>?token=<token>

Pass the token received from the POST /<id>/applications endpoint in a query parameter to render your challenge.

The clock starts against timeLimitHours as soon as this endpoint is called.

POST api/challenges/<id>/queries

Pass the token received from the POST /<id>/applications endpoint in an Authorization header to submit questions about the challenge.

Authorization: Bearer <token>

Request body:

{
  "query": "string"
}

The query will be sent to the support email address set in the front matter. Replies will be sent to the email sent in the POST /<id>/applications request.

POST api/challenges/<id>/submissions

Pass the token received from the POST /<id>/applications endpoint in an Authorization header to submit your solution.

Request body:

{
  "solutionLink": "string"
}

Front Matter Reference

# Email address that will receive messages when applicants submit questions 
# about the challenge via a POST to /<id>/queries
supportEmail: "support@fizzbuzz.md"

# Email address that will receive submissions via a POST to /<id>/submissions
submissionEmail: "submission@fizzbuzz.md"

# Number of hours applicants have to submit their solution. Late submissions are flagged.
timeLimitHours: 72

Usage in Slack

An easy way to set up a challenge so that multiple team members can respond to queries and solutions is to use Slack's email integration feature. If you create separate channels for queries and solutions (e.g., #challenge-queries and challenge-submissions), you can have separate emails for the supportEmail and submissionEmail front matter fields.

Usage in Github Actions

If you'd like to update your challenge file in a Github Actions workflow, you can use download the fizzbuzz.md cli and use it easily in a github action:

steps:
  - name: Download fizzbuzz.md cli
    run: |
      curl https://github.com/kmdupr33/fizzbuzz.md/cli.zx/raw > fbmd
      chmod +x fbmd
  - name: Render challenge file
    env: 
      FBMD_TOKEN: ${{ secrets.FBMD_TOKEN }}
    run: ./fbmd --id=<id> challenge.md

Usage in Github PRs

Reviewing challenges is recommended. Apparently, Github lets you review rich renderings of markdown files in PRs: