Contribution, Environment Setup (GitHub Method)

TDC Contribution Guide - Setting Up Your Environment to Create Content

This process will walk you through setting up your local environment to start writing content for the Tanzu Developer Center. This will also walk you through creating a starter template for each content type.

I need to set up my local environment with the necessary tools to create and test content

1. Install hugo. The VMware Tanzu Developer Center uses Hugo to build the site from Markdown files. You'll need to get Hugo if you want to build and run the site locally. Make sure you install the extended version with SCSS/SASS support built in. This site pins hugo to a specific version (currently 0.82.0) to build so if you're using a different version, your experience may vary. To install this specific version, see the gohugo GitHub releases page for 0.82.0.

   brew install hugo

2. Install NPM. Hugo uses NPM to manage its local packages. If you don’t already have it installed, you will need it to move further.

   brew install npm

3. Install act. act is used to run GitHub Actions tests locally. The Tanzu Developer Center uses GitHub Actions to perform automated testing periodically, and on each pull request. NOTE: Currently, the tests break on act > v0.2.20, be sure to install v0.2.20.)

4. Install Docker. Running automated test locally will require Docker to be running (On Mac OS X requires Docker Desktop 2.4 or newer)

   brew install docker --cask

I AM on the Tanzu Developer Center team with admin rights to the GitHub repository, and I need to clone the repository locally

1. Clone the repository directly from the VMware Tanzu account. This is the primary difference if you have admin rights. Instead of forking the repository, you can simply clone the main repository locally.

   git clone --recurse-submodules https://github.com/vmware-tanzu/tanzu-dev-portal.git

2. Create a working feature branch. This is the branch for which you will eventually submit your pull request.

   git checkout -b $BRANCH_NAME

I AM NOT on the Tanzu Developer Center team with admin rights to the GitHub repository, and I need to clone the repository locally

1. Fork the Tanzu Developer Center. To submit new content to the Tanzu Developer Center, you first need to fork the repo so that later, you can submit a pull request. For more information about how to fork a GitHub repository, check here.

2. Clone your fork of the repository. This will pull down your fork of the Tanzu Developer Center locally.

   git clone --recurse-submodules https://github.com/$GH_USERNAME/tanzu-dev-portal.git

3. Create a working feature branch. This is the branch for which you will eventually submit your pull request.

   git checkout -b $BRANCH_NAME

I need to create a content starter template, and I'm not sure which one

1. Decide on the type of content you want to create. The following is a list of Hugo archetypes currently used by the Tanzu Developer Center. For more information about these archetypes, and help deciding which one your content fits in, see Reference: Content Types.

   Note: Each of the following commands need to be run from the repository root directory (i.e. /path/to/tanzu-dev-portal/)

   • Create a new Guide. Templates will be placed in the /content/guides/ directory. The following will create a What Is Guide, for example:

     make guide.wi.spring.spring-boot-what-is

     to create a Getting Started Guide:

     make guide.gs.spring.spring-boot-gs

   • Create a new blog post. Templates will be placed in the /content/blogs directory. The following command will create a blog post, for example.

     make blog.my-post

   • Create a new Code Sample. Templates will be placed in the /content/samples directory. The following command will create a code sample, for example.

     make sample.my-sample

   • Create a new Video. Templates will be placed in the /content/videos directory. The following command will create a video template, for example.

     make video.my-video

   • Create a new Agile Practice (VMware Employees Only). Templates will be placed in the /content/practices directory. The following command will create an Agile Practice, for example.

     make practice.a-new-practice
     

2. Open the template in your favorite markdown editor. I use Visual Studio Code, but any editor works. For example:

   code content/guides/topic-name/guide-name.md