{"id":20816328,"url":"https://github.com/riptano/astra-portal-getting-started","last_synced_at":"2025-06-17T04:33:56.492Z","repository":{"id":61754787,"uuid":"523779104","full_name":"riptano/astra-portal-getting-started","owner":"riptano","description":"Content home for Astra Portal getting started workflows","archived":false,"fork":false,"pushed_at":"2023-06-09T00:50:07.000Z","size":3000,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-01-18T15:52:30.764Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riptano.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-11T15:40:43.000Z","updated_at":"2023-05-24T18:17:41.000Z","dependencies_parsed_at":"2024-11-17T21:30:07.618Z","dependency_job_id":"c131686e-cc3a-4ab4-8b1d-f6c295984eff","html_url":"https://github.com/riptano/astra-portal-getting-started","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fastra-portal-getting-started","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fastra-portal-getting-started/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fastra-portal-getting-started/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Fastra-portal-getting-started/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riptano","download_url":"https://codeload.github.com/riptano/astra-portal-getting-started/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243164693,"owners_count":20246717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T21:29:46.116Z","updated_at":"2025-03-12T05:28:28.339Z","avatar_url":"https://github.com/riptano.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- \nThis is the overview section. \nThe overview should provide users a high level explanation of what your guide is all about at a glance. \nWhat will they learn, what will they get out of it?\n --\u003e\n# Overview\nHiya. Welcome to the Astra getting started guide template. Use this template to help \"guide\" you through authoring \"getting started\" guides within DataStax Astra. 😏\n\n\"Getting Started\" guides are a unique way to help Astra users learn about a topic or how to perform a set of actions. The goal is to make it dead simple for a user to run through a guide and achieve some goal.\n\nIt is assumed that if you are following this template that you intend to write a guide for DataStax Astra. With that, we highly encourage you to download this markdown file and view it in both edit and rendered modes so you can easily see hidden comments.\n\nIf you'd like to see a working example of this guide [navigate here](https://astra.datastax.com/guide/astraPortalGuideTemplate) and login to Astra.\n\n**In this guide, we will discuss**\n- Creating your guide in Github\n- How to format guides and create actions\n- Configuring your guide\n- What not to do 😬\n- How to submit a guide\n\n# Prerequisites\n**If you don't have any prerequisite content just remove this section altogether.**\n\nThis section contains items that a user may need from outside of Astra. Examples are things like Maven for Java or installing Node or Python. \n- If any prereqs are required be explicit and call them out\n- Provide links to needed resources\n- Here is an example:\n    - [Download](https://maven.apache.org/download.cgi) and [install](https://maven.apache.org/install.html) Maven.\n\nHere's something for fun\n\n![test image for fun](https://media.giphy.com/media/107QsHzZW54hJC/giphy.gif)\n\u003c!--\nYou can use inline links (install) or provide them later with a named reference (Download). Either is fine. Up to you.\n --\u003e\n\n\u003c!-- \nFor each section use ##, the number of the section itself, and the section title. These will automatically\nbe picked up by a preprocessor and used to properly style the guide. While you can generally use \nwhatever markdown you want you don't need to worry about trying to match styles within Astra, we'll do that for you.\nNotice the example below \"## 1 How to get started\".\n --\u003e\n## 1  Creating your guide in Github\n### 1a Pick a name for your guide directory\nTry to make this short and descriptive. \n\nUse **_camelCase_**, _meaning capitalize the first letter of each new word after the first word_. \n\nThis will be the path used in Astra to access your guide.\n\nHere are some examples:\n- introToDataWithAstra\n- overviewOfAstraDB\n- astraDBApplicationQuickstartPython\n\n### 1b Create a directory and your README.md file\nNow that you have a directory name you can create it along with your README.md in Github. \n\nTo do this, click the **_Add file_** drop down in the top right hand corner and choose the **_Create new file_** option within this repo. This will bring you to a page like you see in the image below.\n\n\u003cimg alt=\"Create directory and readme\" src=\"https://github.com/riptano/astra-portal-getting-started/blob/main/createDirectoryAndReadme.png?raw=true\" width=\"100%\" /\u003e\n\nHere, you will both name your guide directory and create a README.md file to work from.\n\nStart off by typing the **_name of the directory for your guide_** in the field provided. Then, type a slash character **_\"/\"_** right after the directory name and add **_README.md_**. \n\nSo in the example above, we typed **_\"yourDirectory/README.md\"_** directly in the field provided.\n\n### 1c Add text to README.md\nIf you already have some text for your **_README.md_** file can you paste it directly into the field provided. \n\n_Note the example \"**Put things here in the README.md file**\" in the image above._\n\n_Also, don't worry if you don't have all of your text ready, you can always edit more later._\n\n### 1d Create a branch\nOk, now we're ready to create a branch.\n\nTo do this, scroll down to the bottom of the page from the previous step.\n\nClick the **_Create a new branch and start a pull request_** radio button.\n\nFill out the branch name in the field provided. Github should automatically fill in your username. Just add your directory name and the word **_\"guide\"_** separated by dashses (for example: **_SonicDMG-yourDirectory-guide_**) as you see in the image below.\n\n\u003cimg alt=\"Create guide branch\" src=\"https://github.com/riptano/astra-portal-getting-started/blob/main/createGuideBranch.png?raw=true\" width=\"100%\" /\u003e\n\nThen click **_Propose new file_**.\n\n### 1e Create a draft pull request\nNow that you have a branch you should see a screen like the one below.\n\n\u003cimg alt=\"Draft pull request\" src=\"https://github.com/riptano/astra-portal-getting-started/blob/main/draftPR.png?raw=true\" width=\"100%\" /\u003e\n\nClick the **_...pull request_** dropdown on the lower right hand corner.\n\nChoose the **_Create draft pull request_** option. The button will change to **_Draft pull request_**.\n\nNow click this button to create a draft pull request. _A draft pull request means you are still making edits and it's not ready for review._\n\n### 1f Navigate to your README.md and edit\nFinally, we need to get to your newly created **_README.md_** and open it for editing. \n\nLook at the image below. \n\nYou should see a link to the branch you just created.\n\nClick this link. This will bring you directly to your newly created branch within Github.\n\n\u003cimg alt=\"Navigate to readme\" src=\"https://github.com/riptano/astra-portal-getting-started/blob/main/navigateToReadme.png?raw=true\" width=\"100%\" /\u003e\n\nNow click on the new directory you added previously.\n\n\u003cimg alt=\"Navigate to directory\" src=\"https://github.com/riptano/astra-portal-getting-started/blob/main/navigateToDirectory.png?raw=true\" width=\"100%\" /\u003e\n\n**_README.md_** should be selected by default. Click on the **_edit_** (_pencil_) icon on the top right to start editing.\n\n\u003cimg alt=\"Edit readme\" src=\"https://github.com/riptano/astra-portal-getting-started/blob/main/editReadme.png?raw=true\" width=\"100%\" /\u003e\n\nOnce you're done with your edits, scroll down to the bottom of the page and **_commit_** your changes to your branch.\n\n_Note: Once you have a draft PR in place you can continue to make changes as needed._ \n\nFollow the sections below to learn how to format your guide. Once complete, the last step (5) will explain how to submit your PR for final review.\n\n## 2 How to format guides and create actions\nGenerally, formatting is pretty open and follows normal markdown styles. The main caveats being guide metadata in the overview, using numbered sections for proper styling within Astra, and using **actions**.\n\n### Uhhh, what are actions?\nGlad you asked. **Actions** are special options that allow you to easily bring a user through a set of Astra specific operations with a simple button click. The goal is to remove friction from the user experience and make it easier for guide creators to add in more complex operations.\n\nAn example is database creation. If you want a user to create a database then use ```\u003c\u003ccreateDatabase\u003e\u003e``` directly in markdown. Again, use **_edit_** mode to see a real example.\n\u003c\u003ccreateDatabase\u003e\u003e\n\nIf you've done this correctly in markdown you'll only see the rendered action. Within an Astra guide this will translate into a fully operational button or link with status updates and other functionality. \n\n_**Note:** **Actions** will potentially bring users into a new flow to complete the **action**, but will then bring users back to the guide once exited._\n\n### Currently available **_actions_** _(these will only render within Astra)_\n```\u003c\u003ccreateDatabase\u003e\u003e```\n\n\u003c\u003ccreateDatabase\u003e\u003e\n\n```\u003c\u003ccreateVectorDatabase\u003e\u003e```\n\n\u003c\u003ccreateVectorDatabase\u003e\u003e\n\n```\u003c\u003ccreateToken\u003e\u003e```\n\n\u003c\u003ccreateToken\u003e\u003e\n\n```\u003c\u003claunchCQLConsole\u003e\u003e```\n\n\u003c\u003claunchCQLConsole\u003e\u003e\n\n```\u003c\u003cdownloadSCB\u003e\u003e```\n\n\u003c\u003cdownloadSCB\u003e\u003e\n\n```\u003c\u003claunchDataLoader\u003e\u003e```\n\n\u003c\u003claunchDataLoader\u003e\u003e\n\n## 3 Configuring your guide\nOk, so now you've got the basics down and have some content. Great, before you submit, there's one more thing for you to do. You must configure your guide.\n\n### Metadata\nEach guide will have it's own section within the config.json. The metadata for THIS guide template looks like this.\n```json\n\"astraPortalGuideTemplate\": {\n  \"locale\": \"en-us\",\n  \"title\": \"Astra Portal Getting Started TEMPLATE 🎇\",\n  \"description\": \"Get an overview of how to write 'getting started' guides for DataStax Astra.\",\n  \"skillLevel\": \"Beginner\",\n  \"timeToComplete\": \"10 minutes\",\n  \"recommendedLinks\": [{\n    \"url\": \"https://www.freecodecamp.org/news/how-to-create-a-local-git-branch/\",\n    \"text\": \"How to create branches in Git\"\n  }, {\n    \"url\": \"https://github.com/markdown-templates/markdown-emojis\",\n    \"text\": \"All the markdown emojis\"\n  }],\n  \"recommendedGuides\": [\n    \"overviewOfAstraDB\"\n  ],\n  \"contentSrc\": \"astraPortalGuideTemplate/README.md\",\n  \"stepCount\": 6\n}\n```\n\nAgain, just use this one as an example for your own guide.\n\n### Breaking it down\nOk, let's break each property down to see what they do.\n\n#### Guide name **_and_** route\nThis one is important. Not only is it the unique name given to your guide, but it determines the route to the guide within Astra. **Case matters!** \n\n```json\n\"astraPortalGuideTemplate\": {\n```\nBy setting this property the route in Astra will be \"https://astra.datastax.com/guide/astraPortalGuideTemplate\"\n\n#### Guide details\nThe guide detail section will give users high level information about your guide. Things like the `title`, a short `description`, `skill level`, and approx. `time to complete`.\n\nThe `title` should conform to **20** chars min, **73** chars max.\n\nThe `description` should conform to **40** chars min, **110** chars max.\n```json\n\"locale\": \"en-us\", // just use this value for now\n\"title\": \"Astra Portal Getting Started TEMPLATE 🎇, but I need more to hit 73 chars🚀\",\n\"description\": \"Get an overview of how to write 'getting started' guides for DataStax Astra and then keep going to 110 chars.🌈\",\n\"skillLevel\": \"Beginner\",\n\"timeToComplete\": \"10 minutes\",\n```\nEach of these values will then be automatically rendered within Astra, both in the title cards displayed on the home page and within the guides themselves.\n\n#### Recommended Links\nWhile you may include inline links for content, guides also include explicit resource call outs in the right-hand side navigation. These are for links you really want to bring attention to and should be constrained to just a few links at most. \n\nThe example below contains two links that will be displayed under the auto-generated table of contents to the right.\n```json\n\"recommendedLinks\": [{\n  \"url\": \"https://www.freecodecamp.org/news/how-to-create-a-local-git-branch/\",\n  \"text\": \"How to create branches in Git\"\n}, {\n  \"url\": \"https://github.com/markdown-templates/markdown-emojis\",\n  \"text\": \"All the markdown emojis\"\n}],\n```\n\n#### Recommended guides\nIf your guide is part of a larger set or you want to point users to a different guide upon completion of your guide use the \"recommendedGuides\" property to do this. Similar to recommended links you can provide multiple guides if you wise. \n\nValues you use within the `recommendGuides` section **MUST MATCH** guide names from the config.json **EXACTLY**.\n\n```json\n\"recommendedGuides\": [\n  \"overviewOfAstraDB\", \"introToDataWithAstraDB\"\n],\n```\n\n#### Source and step count\nFinally, we come to the `contentSrc` and `stepCount` properties. \n\nThe `contentSrc` property tells the guide renderer where in the repository your guide exists. If this value is incorrect your guide will not render. \n\nThe `stepCount` property tells the renderer how many steps you have in your guide. For example, this guide has six steps ending with \"6 How to submit a guide\". So, the `stepCount` in this case should be \"6\". The renderer will do the rest and auto-generate the table of contents and all that.\n```json\n    \"contentSrc\": \"astraPortalGuideTemplate/README.md\",\n    \"stepCount\": 6\n}\n```\n## 4 What not to do 😬\nWe ask that you don't include artifacts that go stale, like UI screenshots that change over time. Our goal is to provide guides that are as maintenance free as possible for both you and our users. Nothing like using a guide that was great a year ago only to find out nothing in it works halfway through.\n\n## 5 How to submit a guide\nOk great, your guide is ready and now you want to submit a pull request (PR) to get it published. All we need to do is mark your draft pull request \"Ready for review\" in the **_Pull requests_** tab in Github. \n\nClick the **_Pull requests_** tab.\n\nClick on your pull request.\n\nClick the **_Ready for review_** button.\n\nThat's it! At this point one of the review team will be notified to start reviewing your request. Awesome job!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friptano%2Fastra-portal-getting-started","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friptano%2Fastra-portal-getting-started","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friptano%2Fastra-portal-getting-started/lists"}