From 782892008b29533344f9208a3640657a28b10bf8 Mon Sep 17 00:00:00 2001 From: Tamimi Date: Wed, 13 Nov 2024 08:12:22 -0800 Subject: [PATCH] Update codelab for codelab creation instructions --- README.md | 25 +-- init.sh | 7 +- .../codelab-4-codelab/codelab-4-codelab.md | 184 ++++++------------ markdown/codelab-4-codelab/package.json | 2 +- markdown/exportAll.sh | 9 - 5 files changed, 69 insertions(+), 158 deletions(-) delete mode 100755 markdown/exportAll.sh diff --git a/README.md b/README.md index 7f852f5a..064a2fd3 100644 --- a/README.md +++ b/README.md @@ -20,28 +20,9 @@ This repository is included as a submodule in the main [site repo](https://githu 1. Navigate to the newly cloned directory `cd solace-dev-codelabs` 1. Checkout a local branch for your new codelab `git checkout -b add-codelab-` -### Option 1 - Script -1. [Setup your environment](https://codelabs.solace.dev/codelabs/codelab-4-codelab/index.html?#1) -1. [Read the solace guidelines](https://codelabs.solace.dev/codelabs/codelab-4-codelab/index.html?#2) -1. From the root directory, run `./init.sh ` script -1. Navigate to `/markdown/name-of-codelab` -1. Run the following from terminal `npm install; npm run watch` -1. Edit your `.md` file in your text editor of choice -1. When ready, run `export.sh` -1. Navigate to the codelabs root directory (`cd ../../`), add and commit your changes in a PR. From the root directory, -``` -cd ../../ #to navigate to the root of the codelabs dir -git add . -git commit -m "add new codelab: " -git push origin add-codelab- -``` -Note: _origin_ in the command above the name of the remote repository. If your remote repository is of a different name then you will have to `git push add-codelab-` - -### Option 2 - Manual - -Follow the steps in this tutorial: https://codelabs.solace.dev/codelabs/codelab-4-codelab - -Note: original markdown of this codelab is found under [codelabs/codelab-4-codelab](./codelabs/codelab-4-codelab) +### Create your own Codelab + +Follow the steps found in the [Codelab to Create a Codelab](https://codelabs.solace.dev/codelabs/codelab-4-codelab/index.html?#1) codelab ## Learn About CodeLab * CodeLabs are being created using Google Codelabs: https://github.com/googlecodelabs/tools diff --git a/init.sh b/init.sh index 4c3c366e..83eeab61 100755 --- a/init.sh +++ b/init.sh @@ -11,7 +11,7 @@ command_exists() { # check if command exists and fail otherwise command -v "$1" >/dev/null 2>&1 if [[ $? -ne 0 ]]; then - echo "Note: $1 Does not exist. Please install it first!" + echo "Note: $1 Does not exist. Please install it if you would like to run the codelab locally" fi } @@ -80,6 +80,7 @@ if [ -f "$backup_package_json" ]; then fi echo "Markdown file created! Find it at $PWD/markdown/$CODELAB_NAME" - command_exists claat -command_exists go \ No newline at end of file +command_exists go + +cd $PWD/markdown/$CODELAB_NAME \ No newline at end of file diff --git a/markdown/codelab-4-codelab/codelab-4-codelab.md b/markdown/codelab-4-codelab/codelab-4-codelab.md index b80ae729..ce987391 100644 --- a/markdown/codelab-4-codelab/codelab-4-codelab.md +++ b/markdown/codelab-4-codelab/codelab-4-codelab.md @@ -13,9 +13,9 @@ feedback link: https://github.com/SolaceDev/solace-dev-codelabs/tree/master/mark Duration: 0:02:00 -Are you trying to create easy to use, visually appealing content for the tech community? This Codelab will show you how to quickly create your own Google Codelab just like the one you're using right now. +This Codelab will show you how to quickly create your own Google Codelab just like the one you're using right now! -We'll be authoring the codelabs using markdown format. This gives us the flexibility of using our markdown file for other things and also storing it in our [github repo](https://github.com/SolaceDev/solace-dev-codelabs) with any code that might be used for a tutorial. +We'll be authoring the codelabs using markdown format. This gives us the flexibility of using our markdown file for other things and also storing it in our [github repo](https://github.com/SolaceDev/solace-dev-codelabs/tree/master/markdown). Here is an example image of another Codelab that I created: ![image_caption](img/codelabexample.png) @@ -24,33 +24,32 @@ Here is an example image of another Codelab that I created: - The markdown for this codelab is located here: [codelab.md](https://raw.githubusercontent.com/SolaceDev/solace-dev-codelabs/master/markdown/codelab-4-codelab/codelab-4-codelab.md) - [Google Codelabs Tools Github](https://github.com/googlecodelabs/tools) - The repo that contains the claat tool we'll be using today - [Google Group for Codelab Authors](https://groups.google.com/forum/#!forum/codelab-authors) - great forum for asking questions about codelabs and discussing future functionality -- [A blog that I used when getting started with Google Codelabs](https://medium.com/@mariopce/tutorial-how-to-make-tutorials-using-google-code-labs-gangdam-style-d62b35476816) -### Video +## Environment Setup -You can also watch a video on how you can contribute to authoring a codelab by visiting this [YouTube link](https://www.youtube.com/watch?v=2B8ev-hSbcM) or watching the video below +Duration: 0:04:00 -![https://www.youtube.com/watch?v=2B8ev-hSbcM](Video) +Authoring a new codelab is as simple as writing your content in markdown format and opening pull request in the codelabs repo as defined in steps 4, 5, and 8. Please refer to the Tips and Tricks: Syntax step to keep note of codelab specific syntax that you will need to follow for the correct formatting. -## Environment Setup +Note that you can view your markdown file using a markdown viewer of your own (e.g. a viewer embedded in VsCode, or online tool) + +### Optional, But Recommended +If you would like to view your codelab locally in the same format before contributing to the main [codelabs site](https://codelabs.solace.dev/), follow the steps below to mimic the environment used to build codelabs 👇 -Duration: 0:04:00 -In order to create a Codelab you need +You will need to have the following dependencies - [Go](https://golang.org/dl/) -- [claat](https://github.com/googlecodelabs/tools/tree/master/claat) (the codelabs command line tool) installed. +- [claat](https://github.com/googlecodelabs/tools/tree/master/claat) (the codelabs command line tool) - [Nodejs](https://nodejs.org/en/download/) -You have two options to download the dependencies: - ### Option A: Download from source - Install Go, claat, and NodeJs from the links above if you don't have them already installed. You can follow the documentation on Go's website and the Google Codelabs github repo. ### Option B: Download from cli: MacOS/Linux setup -#### Install Go +#### Make sure you Go installed in your system ```bash $ brew install go @@ -61,23 +60,16 @@ $ brew install go Below is what I set on mac, but instructions are [here](https://golang.org/doc/install) for other OS options ```bash -$ export GOPATH=$HOME/Go -$ export GOROOT=/usr/local/opt/go/libexec +$ export GOPATH=$HOME/go $ export PATH=$PATH:$GOPATH/bin -$ export PATH=$PATH:$GOROOT/bin ``` #### Install claat -**Option A: from CLI using go** - ```bash $ go install github.com/googlecodelabs/tools/claat@latest ``` -**Option B: pre-compiled binary** - -Navigate to the [Google Codelabs release page](https://github.com/googlecodelabs/tools/releases) and install it from there #### Confirm claat installment @@ -86,19 +78,6 @@ You should now have the _claat_ command available to you. ```bash $ claat ``` - - -#### Note if you have Go v1.17+ - -As of Go v1.17+, the go get command for installing executables is deprecated https://go.dev/doc/go-get-install-deprecation - -A workaround for isntalling the claat command is the follwing: -1. Clone the google tools project repo into a google-tools directory `git clone git@github.com:googlecodelabs/tools.git google-tools` -2. Navigate to the claat command directory `cd google-tools/claat` -3. Build the claat command `go build .`. This will create a `claat` command executable that you can use. -4. Now you can update your PATH env variable (this is either done in your .bashrc, .profile, or .zshrc depending on what your shell is). At the end of the file, isert the following line`export PATH=$PATH:$HOME/google-tools/claat`. Note: this assumes you clones the google-tools repo in your $HOME directory. If cloned elsewhere, make sure you use the right path in your path export -5. After you do this, you can open up a new terminal window and executing `claat` from the command line should work - ## Solace Guidelines Duration: 0:05:00 @@ -122,8 +101,8 @@ Duration: 0:05:00 ### Where to create your codelab 📌 Create your codelab in the [Solace codelabs repo](https://github.com/SolaceDev/solace-dev-codelabs) for version tracking -📌 All other code can be kept in a separate repo -📌 Example codelab markdown structure can be found on the [Battleship markdown](https://github.com/SolaceDev/solace-dev-codelabs/tree/master/markdown/solace-battleship) and the [Battleship source code](https://github.com/solacetraining/solace-battleship) +📌 All other code referenced in your codelab should be kept in a separate repo +📌 Example codelab markdown structure can be found in the [codelabs repo](https://github.com/SolaceDev/solace-dev-codelabs/tree/master/markdown). ### Content Reviewer @@ -138,21 +117,21 @@ Upon authoring of your codelab, we request you have two reviewers: Duration: 0:02:00 -Start by - -1. Forking the solace-dev-codelabs repo from [https://github.com/SolaceDev/solace-dev-codelabs](https://github.com/SolaceDev/solace-dev-codelabs) - ![image_caption](img/fork.png) +1. Fork the solace-dev-codelabs repo from [https://github.com/SolaceDev/solace-dev-codelabs](https://github.com/SolaceDev/solace-dev-codelabs) -2. Clone your fork. Note: replace `` with your github username and `` with the name of your codelabs. See note below if you do not have ssh setup +2. Clone your fork ```bash git clone git@github.com:/solace-dev-codelabs.git cd solace-dev-codelabs git checkout -b add-codelab- ``` +> aside positive +> Replace `< Your_Github_User >` with your github username and `< name_of_codelab >` with the name of your codelabs. + > aside positive -> If you do not have SSH setup on your machine and got an error cloning the repo, you can clone the https link instead as follows: +> If you do not have [SSH setup](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) on your machine and got an error cloning the repo, you can clone the https link instead as follows: > ``` > git clone https://github.com//solace-dev-codelabs.git > ``` @@ -160,54 +139,42 @@ git checkout -b add-codelab- > aside negative > Do not forget to checkout the code into a new branch **git checkout -b \**. This would help facilitating a peer review and approve/reject changes without affecting the published content. -Then follow one of the two options in the next two steps: Automated or Manual -## Create a new Codelab - Automated [Option A] +## Create a new Codelab Duration: 0:05:00 ### Prerequisites -- NodeJS +- [Optional] NodeJS ### Steps -1. After cloning the repository as per the earlier step, from the root directory, run the init script as follows `./init.sh ` -1. Navigate to the `/markdown/` directory -1. Install the required dependencies for watching any changes you make in your markdown file by running the following from terminal `npm install` -1. Compile and start the claat server by running `npm run watch`. Note: This will open a tab in your browser and serve your markdown file -1. Edit your `.md` file in your text editor of choice -1. When ready, run the export script as follows `./export.sh` +1. After cloning your fork of the repository and checking out a new branch as per the earlier step, from the root directory, run the init script as follows `source init.sh < name-of-codelab >` +1. You should now be in your `/markdown/< name-of-codelab >` directory +1. [Optional] Install the required dependencies for watching any changes you make in your markdown file by running the following from terminal `npm install` +1. [Optional] Compile and start the `claat` server by running `npm run watch`. Note: This will open a tab in your browser and serve your markdown file +1. Edit your `< name-of-codelab >.md` file in your text editor of choice > aside negative > If you're using Windows make sure to set your text editor to use UNIX line endings! -> aside positive -> Exporting your codelab will create the html static files under the `codelabs/` directory - 🚀 Go ahead to the **Step 8** and add your codelabs on the main repo -## Create a new Codelab - Manual [Option B] - -Create a folder `` under the `markdown` directory. This is where your markdown file and related artifacts (such as images) will reside. - -Navigate to the `` directory. +## Tips and Tricks: Syntax -Go ahead and create a markdown file where you'll create the actual codelab. -Please have your markdown file name match the `id` in the header metadata that you will set in the next subsection. > aside negative > If you're using Windows make sure to set your text editor to use UNIX line endings! -#### - +### Open your markdown file ```bash -$ vim unique-codelab-identifier.md +$ vim .md ``` -#### Fill-in the header metadata +#### Header metadata [Auto generated] -Copy and paste the headers below into your markdown file and change the values appropriately. +Update the headers metadata in your markdown file and change the values appropriately. Guidelines are available below the sample headers. ``` @@ -227,21 +194,20 @@ At present, values must all be on one line. All metadata must come before the title. Any arbitrary keys and values may be used; however, only the following will be understood by the renderer: -- Author: Author name or git username -- Summary: A human-readable summary of the codelab. Defaults to blank -- Id: An identifier composed of lowercase letters ideally describing the content of the codelab. This field should be unique among codelabs. This will be in the URL of the codelab -- Tags: Leave "workshop" if creating a Developer workshop or "iguide" if creating an integration guide. Remove both if neither. Note: this is used for the "Filter by Type" feature on the [landing page](solace.dev/codelabs) -- Categories: A comma-separated list of the topics or technologies the codelab covers. Include items such as language(s) and protocol(s) used. The first one is used to create a new "Filter by category" feature on the [landing page](solace.dev/codelabs) and the styling of the category. The remaining will be used for the filtering. - - Note that the list of available categories can be found in the main [site repo](https://github.com/SolaceDev/solace-dev-codelabs-site/blob/master/site/app/styles/_categories.scss#L178-L198) - - The current list is (case insensitive): `[AMQP, Boomi, Codelab, Java, JMS, Kafka, MQTT, REST, Solace, Spring]` -- Environments: Leave as "Web" -- Status: The publication status of the codelab. Valid values are: +- `Author`: Author name or git username +- `Summary`: A human-readable summary of the codelab. Defaults to blank +- `Id`: An identifier composed of lowercase letters ideally describing the content of the codelab. This field should be unique among codelabs. This will be in the URL of the codelab +- `Tags`: Leave "workshop" if creating a Developer workshop or "iguide" if creating an integration guide. Remove both if neither. Note: this is used for the "Filter by Type" feature on the [landing page](solace.dev/codelabs) +- `Categories`: A comma-separated list of the topics or technologies the codelab covers. Include items such as language(s) and protocol(s) used. The first one is used to create a new "Filter by category" feature on the [landing page](solace.dev/codelabs) and the styling of the category. The remaining will be used for the filtering. + - Note that the list of available categories can be found in the main [site repo](https://github.com/SolaceDev/solace-dev-codelabs-site/blob/master/site/app/styles/_categories.scss#L152-L181) + - The current list is (case insensitive): `[amqp, boomi, codelab, java, jms, kafka, mqtt, rest, solace, spring, kubernetes, javascript, helm, azure, opentelemetry, mulesoft, rabbitmq, keda, apama, hermesjms, flink, nifi, nagios, jboss, weblogic, websphere, webspherelib, spark, sap, terraform]` +- `Environments`: Leave as "Web" +- `Status`: The publication status of the codelab. Valid values are: - Draft: Codelab is not finished. - Published: Codelab is finished and visible. - Deprecated: Codelab is considered stale and should not be widely advertised. - Hidden: Codelab is not shown in index. -- Feedback Link: A link to send users to if they wish to leave feedback on the codelab. Link to git repo where code for the tutorial will live. -- Analytics Account: A Google Analytics ID to include with all codelab pages. Leave as shown above. +- `Feedback Link`: A link to send users to if they wish to leave feedback on the codelab. Link to git repo where code for the tutorial will live. #### Add the Title @@ -253,9 +219,12 @@ Next add your title using a single '#' character #### Add Sections & Durations -Then for each section use Header 2 or '##' & specify an optional duration beneath for time remaining calculations -Optional section times will be used to automatically total & remaining tutorial times -In markdown I've found that the time is formatted hh:mm:ss +Then for each section use Header 2 or '##' & specify q duration beneath for time remaining calculations + +> aside positive +> Duration is in the following time format" +> +> `hh:mm:ss` Example @@ -325,49 +294,20 @@ Add an image! More Markdown Parser examples can be found [here](https://github.com/googlecodelabs/tools/tree/master/claat/parser/md). -### Export & Serve Locally +### Serve Locally -Now that you have an initial codelab defined in your markdown file let's go ahead and generate the static site content. -We can export & serve the content locally using the `claat` command that we installed earlier. +Now that you have an initial codelab defined in your markdown file let's go ahead and serve the codelab locally to view it. +Simply run the following command ```bash -$ claat export codelab.md -$ claat serve +$ npm install +$ npm run watch ``` -- Your browser should have opened (if it doesn't then try going to [http://localhost:9090/](http://localhost:9090/) in your browser). -- Choose the directory that matches your "id" that you put in the headers. -- Viola! You should have your first codelab! - -Repeat the export and serve locally every ime you make a new change in the markdown file - -> aside positive -> When you ran the `claat export` command you created the static web content needed to host your codelab. -It placed static web content in a directory specified by your unique "id" and you can view it locally by opening the index.html page. - -> aside negative -> Note that when you view it locally by opening index.html some of the graphics may not show up (such as access_time, Next, Back), but they work once online. - -### Export for production - -When you're done, export your static web content to the `codelabs` folder. +Your browser will automatically launch to the hosted markdown file! > aside positive -> Make sure your markdown file name matches your header metadata `id` for ease of future updates. - -```bash -# If creating a new codelab -mkdir markdown/ -# Add your markdown content in the markdown//.md directory -# Add your images in the markdown//img directory - -cd markdown/ -# Export into static content -# Note the google analytics code used. Keep as is below -claat export -o ../../codelabs/ .md -``` -> aside positive -> Exporting your codelab will create the html static files under the `codelabs/` directory +> Every time you save your markdown file the browser will refresh the latest content 🚀 Go ahead to **Step 8** and add your codelabs on the main repo @@ -380,29 +320,27 @@ Duration: 0:03:00 1. Navigate to the `/markdown/` directory 2. Compile and start the claat server by running `npm run watch`. Note: This will open a tab in your browser and serve your markdown file 3. Edit your `.md` file in your text editor of choice -4. When ready, run the export script as follows `./export.sh` > aside negative > If you're using Windows make sure to set your text editor to use UNIX line endings! -> aside positive -> Exporting your codelab will create the html static files under the `codelabs/` directory - 🚀 Go ahead to **Step 8** and add your codelabs on the main repo -## Add your Codelab to solace.dev/codelabs +## Contribute your Codelab Duration: 0:05:00 ### Stage your Codelab -Add your changes and any newly created files, then commit & push the changes. From your **codelabs root** directory, execute: +Add your changes and any newly created files, then commit & push the changes to your forked repo. From your **codelabs root** directory, execute: ```bash cd solace-dev-codelabs +# If you use npm run watch to serve markdown locally, make sure the temp directory is deleted +rm -fr /markdown//temp git add . git commit -m 'Added or Updated codelab' -git push origin add-codelab- +git push origin add-codelab- ``` ### Create a Pull Request diff --git a/markdown/codelab-4-codelab/package.json b/markdown/codelab-4-codelab/package.json index 0b36cc4d..8656a1a2 100644 --- a/markdown/codelab-4-codelab/package.json +++ b/markdown/codelab-4-codelab/package.json @@ -4,7 +4,7 @@ "description": "use nodemon to watch changes on md file, rebuild codelab on saves", "main": "index.js", "scripts": { - "watch": "nodemon --watch codelab-4-codelab.md --exec 'claat export codelab-4-codelab.md && lsof -i :9090 -t | xargs kill && cd codelab-4-codelab && claat serve'" + "watch": "nodemon --watch codelab-4-codelab.md --exec 'claat export -o temp/ codelab-4-codelab.md && lsof -i :9090 -t | xargs kill && cd temp/codelab-4-codelab && claat serve'" }, "repository": { "type": "git", diff --git a/markdown/exportAll.sh b/markdown/exportAll.sh deleted file mode 100755 index 4393281c..00000000 --- a/markdown/exportAll.sh +++ /dev/null @@ -1,9 +0,0 @@ -for d in * -do - if [ "$d" == *"template"* ] || [ "$d" == *"integrations"* ] || [ "$d" == *"exportAll.sh"* ] - then - continue - fi - cd "$d" && ./export.sh - cd - -done