From 98b07188c6c23d87d73e88e5e2c416dfdbc1ff01 Mon Sep 17 00:00:00 2001 From: Erin Cochran Date: Wed, 17 Jul 2024 16:27:16 -0400 Subject: [PATCH] [docs] - Add Dagster University section to docs README (#23062) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary & Motivation This PR adds a section about authoring Dagster University content to the docs README. ## How I Tested These Changes 👀 --- docs/README.md | 7 ++++ docs/dagster-university/README.md | 63 +++++++++++++++++++++++++------ 2 files changed, 59 insertions(+), 11 deletions(-) diff --git a/docs/README.md b/docs/README.md index 99ab80db99ec7..6379a149b4344 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,7 @@ The content for the site is of several types and stored in several places: - [**Code snippets**](#code-snippets) are embedded throughout the prose docs. All code snippets used in the docs site live (outside the `docs` folder) in `examples/docs_snippets`. This is just a regular python package, which makes it easy to test and specify dependencies for the snippets. - [**Screenshots**](#screenshots) are image files living in `next/public/images`, typically under a subdirectory corresponding to the page on which they appear. There's no need to manually manage the screenshots in this directory-- instead you can add a specification your screenshot to `screenshots` and run `dagster-ui-screenshot capture` to quasi-automatically generate the screenshot and place it in the appropriate subdirectory of `next/public/images`. - [**Navigation schema**](#navigation-schema) is a JSON file specifying the contents of the main nav for the site (found in the left sidebar). This typically needs to be updated to include a link when new prose doc is added. +- [**Dagster University**](#dagster-university) is a separate Nextjs site containing the content for Dagster University courses. ## Prose docs @@ -133,6 +134,12 @@ Most of the site's images are screenshots of the Dagster UI. There is a semi-aut If you are adding a new prose page or want to update the navigation in the sidebar, update the `docs/content/_navigation.json` file. The structure is self-explanatory when looking at the sidebar. +## Dagster University + +Refer to the Dagster University [README](https://github.com/dagster-io/dagster/tree/master/docs/dagster-university) for more info about working in this directory. + +--- + ## Troubleshooting ### Problem: ModuleNotFoundError: No module named 'X' diff --git a/docs/dagster-university/README.md b/docs/dagster-university/README.md index 3854b49039c77..995c1f7f08429 100644 --- a/docs/dagster-university/README.md +++ b/docs/dagster-university/README.md @@ -1,8 +1,8 @@ -# Full Next.js example +# Dagster University -This is a full-featured boilerplate for a creating a documentation website using Markdoc and Next.js. +This directory contains the content for Dagster University, located at https://courses.dagster.io. The site is built with [NextJS](https://nextjs.org/) and [Markdoc](https://markdoc.dev/). -image +--- ## Setup @@ -14,7 +14,7 @@ npm install yarn install ``` -Then, run the development server: +To serve the site locally in development mode (hot-reloading), run: ```bash npm run dev @@ -24,16 +24,57 @@ yarn dev Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. -You can start editing the page by modifying `index.md`. The page auto-updates as you edit the file. +--- -## Deploy +## Authoring -The quickest way to deploy your own version of this boilerplate is by deploying it with [Vercel](https://vercel.com) or [Netlify](https://www.netlify.com/) by clicking one of the buttons below. +Course content lives in `/dagster-university/pages`. Each course has: -### Deploy with Vercel +- A category page, located in the directory root, ex: `/../../dagster-essentials.md`. Links to individual lessons are added to these pages to make it easier to navigate the site locally. +- A dedicated subdirectory, ex: `/../../dagster-essentials`, which contains a folder for each lesson in the course. -[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/markdoc/next.js-starter) +### Lesson content -### Deploy to Netlify +Learn best by example? Check out this PR to see how to [add a new lesson to a course](https://github.com/dagster-io/dagster/pull/20096). -[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/markdoc/next.js-starter) +### Formatting with Markdown + +We use [Markdoc](https://markdoc.dev/), a flavor of Markdown, to author our content. This flavor of Markdown is similar to that used on GitHub, but with some additional capabilities. Refer to the [Markdoc syntax documentation](https://markdoc.dev/docs/syntax) for more information. + +#### Tables + +Commonmark tables are supported, but you can also use list formatting to construct tables. For example: + +```markdown +## commonmark table + +| Name | ID | Description | +|-------|----|----------------------------| +| Daggy | 1 | The most educated octopus. | +``` + +Becomes the following in Markdoc syntax: + +```markdown +## markdoc table + +{% table %} +* Name +* ID +* Description +--- +* Daggy +* 1 +* The most educated octopus. +{% /table %} +``` + +Refer to the [Markdoc table documentation](https://markdoc.dev/docs/tags#table) for more information and examples. + +--- + +## Getting help + +- Join the [Dagster Slack](https://dagster.io/community) community and ask a question in our `#dagster-university` channel +- Find solutions and patterns in our [GitHub discussions](https://github.com/dagster-io/dagster/discussions) +- Check out the [Dagster Docs](https://docs.dagster.io/) \ No newline at end of file