Skip to content

Commit

Permalink
[docs] - Add Dagster University section to docs README (#23062)
Browse files Browse the repository at this point in the history
## Summary & Motivation

This PR adds a section about authoring Dagster University content to the
docs README.

## How I Tested These Changes

👀
  • Loading branch information
erinkcochran87 authored Jul 17, 2024
1 parent a09ac1b commit 98b0718
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 11 deletions.
7 changes: 7 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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'
Expand Down
63 changes: 52 additions & 11 deletions docs/dagster-university/README.md
Original file line number Diff line number Diff line change
@@ -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/).

<img width="2032" alt="image" src="https://user-images.githubusercontent.com/62121649/174916143-16f18270-0463-402c-8b48-33c627ea7a7e.png">
---

## Setup

Expand All @@ -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
Expand All @@ -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/)

1 comment on commit 98b0718

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deploy preview for dagster-university ready!

✅ Preview
https://dagster-university-m5tb7aplc-elementl.vercel.app

Built with commit 98b0718.
This pull request is being automatically deployed with vercel-action

Please sign in to comment.