Do you have a boatload of speaking gigs?
Use the gigsboat CLI to manage them all via GitHub in the open source way!
Track your speaking activities all within your GitHub opensource repository!
Here is how I'm doing it:
- Are you a Developer Advocate 🥑 ?
- Enjoy doing conference talks, meetups presentations, or joining a podcast?
- Do you have a boatload of speaking gigs?
Gigsboat is for you becasue:
- It is difficult for you to keep track of all of your gigs
- You want some stats and hard cold data for all of your speaking engagements
Welcome to gigsboat ⛵️ 🎉
Even more reasons to use Gigsboat:
-
You own your data - do you use a 3rd-party app, or tool to manage your talks? Maybe a Trello board? With gigsboat, you own and manage your data via YAML files, and gigsboat is here to help you transform that into a beautiful Markdown page.
-
It's all open source - Well, gigsboat is open source but also all of your speaking activities, they're all open source and all managed right here in GitHub where it's easy to manage your talks, just like you manage your code projects. It's all transparent and you can share it with your friends, conference organizers, and so on.
-
Zero config - just run the CLI tool and it'll automatically detect source files, and generate a Markdown document for you with all of them.
-
Statistics - gigsboat runs some numbers crunching and gives you stats about your speaking engagements!
- You run the CLI
- It finds your events' data files
- It parses them into JSON
- It extracts, and sorts the data in all kinds of way
- Exports the JSON into Markdown format
- Results are printed to STDOUT or to a
README.mdfile - You now have a fancy looking Markdown document that lists all of your events
We have a template repository for you to get started in a matter of seconds! 🚤
Head over to the gigs-template repository which we created as a template for you to quickly get started. It's just a few steps, and you can start tracking all of your speaking engagements.
If you would like to know the gritty details of how the gigsboat CLI works, continue to read for the starting from scratch section.
If you're just getting started tracking your events and you don't have any actual data files that hold the history of your events (or your upcoming events), then this section is for you.
It boils down to the following:
- You need a directory structure (any structure you choose) with data files inside it
- Those data files need to be in YAML Front Matter format. Those YAML files need to have a specific format.
Now, let's break it down further to give you example code you can get started with.
You are probably going to manage it all via a repository, so once you have one created, here's a suggested directory structure:
- gigsboat.json
- pages
|
- 2020
|
- 2020-02-03.md
- 2020-06-03.md
- 2021
|
- 2021-11-26.md
In the above we are nesting all of the data files under pages/<year>/ directories.
You are free to create whatever directory structure that makes sense for you, but note that gigsboat will by default search the data files under the pages root directory in which it runs.
The gigsboat.json file is used as a configuration file for the gigsboat cli.
Note: the data filenames can be anything. In this example, it shows a simple date format of yyyy-mm-dd however that may not always work - for example, when you have two speaking engagements (a podcast recording, and a meetup talk) on the same day. That said, the filename doesn't matter at all, and you can then follow a convention, of say, 2021-11-26-2.md which adds a suffix of incrementing numbers to the day.
The data files are markdown, but they need to have the following YAML Front Matter format:
---
date: 2019-05-30
tags: post
name: OWASP Global AppSec
url: https://telaviv.appsecglobal.org/
type: conference
title: Black Clouds Silver Linings In Nodejs Security
slides_url: https://drive.google.com/file/d/1s0YIvnlF7ByoESu3rHV2i5M9_jQSXjyR/view
recording_url: https://www.youtube.com/watch?v=4XdF4OiAAzU&feature=emb_logo&ab_channel=OWASP
city: Tel Aviv
country: Israel
country_code: IL
language: English
recognitions:
twitter:
- https://twitter.com/_r3ggi/status/1134057317538942978
image_header: https://pbs.twimg.com/media/D7z7G5dXsAA3ulw?format=jpg&name=small
images:
- https://pbs.twimg.com/media/D7z7G5dXsAA3ulw?format=jpg&name=small
---For brevity, the above also includes example values to each of the field so that the schema for the data files is easily understood.
You can save this data file as say 2019-05-30.md in your pages/ directory somewhere. As you can see, there's a dedicated date field, which gigsboat will parse and is the reason that the filename convention doesn't actually matter.
You might wonder why is this referred to as a markdown file? because the front matter piece of it all the YAML structure between the opening and closing ---, after which, it can have a markdown-formatted content, so you can treat it as a markdown document for any purpose. Some ideas: you may want to capture your own personal notes of that event, maybe add pictures, add your summary and so on.
There are currently 6 supported values for the type property within the YAML Front Matter. The gigsboat cli will count how many of each of these exist, and create a badge with that count on the generated README.md file.
These values are:
- conference
- podcast
- webinar
- meetup
- article
- workshop
It is possible to use any free form text in the type property, however, when these aren't matched against the above, they will be counted in a fallback type called 'other'.
This is the configuration file for the gigsboat CLI. This contains four sections:
inputsourceDirectory- this is the relative path to the directory in which the data files for the generated file are located
outputmarkdownFile- this is the name of the file that should be generated
preContent- a collection of raw or formatted HTML to place at the start of the generated filepostContent- a collection of raw or formatted HTML to place at the end of the generated file
A complete example of this configuration file:
{
"input": {
"sourceDirectory": "pages"
},
"output": {
"markdownFile": "README-gigs.md"
},
"preContent": [
{
"raw": "<p align='center'><h1 align='center'>This will appear at the top of the generated README.md file</h1>"
},
{
"raw": "<p align='center'>Let's add some badges! <p align='center'><a href='https://twitter.com/liran_tal'><img alt='Twitter Follow' src='https://img.shields.io/twitter/follow/liran_tal?style=social'></a></p>"
},
{
"format": [
{
"ul": [
"In addition to raw HTML elements, you can use format sections",
"Using HTML elements to construct the output"
]
}
]
}
],
"postContent": [
{
"raw": "<p align='center'><h1 align='center'>This will appear at the bottom of the generated README.md file</h1>"
}
]
}Use the gigsboat CLI to manage them all!
Use npm's built-in npx command to fetch, install, and run gigsboat with no configuration on your current project:
npx @gigsboat/cliIt is possible to deploy the generated README.md file to github pages. All that is needed, is to enable github-pages in the repository's settings > pages, as is described in the github pages docs, starting from step 3.
To access the generated site visit
https://<username-or-org>.github.io/<template-repo-name>
To select a different theme than the default or to customise it, add a _config.yml file and include theme: jekyll-theme-minimal. From the same _config.yml file, it's also possible to set a title and description for the gerated html. For more details on theme customisation follow the steps described in adding a theme to your jekyll site.
You can use several static site generators to output an html from the generated README.md file. Using jekyll, is great if you want to deploy to github pages. But if you're looking to deploy somewhere else, you might want to use a different tool like 11ty. We have created a guide in GENERATE_11ty_STATIC_SITE.md to get you started.
Please consult CONTRIBUTING for guidelines on contributing to this project.
@gigsboat/cli © Liran Tal, Released under the Apache-2.0 License.