This package contains the source code for docs.goldsky.com. For each pull request, there is a preview deployment available. When a pull request is merged into the main branch, the changes get deployed to docs.goldsky.com.
- Clone the repository to your local machine using
git clone https://github.com/goldsky/docs.git
- Navigate to the cloned repository using
cd docs
- Install the necessary dependencies using
npm install
- Start the local development server using
npm run dev
- Open your web browser and navigate to
http://localhost:3000
to preview the documentation.
Diagrams are part of a single Excalidraw canvas.
To create a new diagram or edit an existing one:
- Navigate to https://excalidraw.com
- Click the ☰ menu at the top left, select Open
- Alternatively, press Ctrl/Cmd + O on the canvas
- Select the
goldsky-docs-diagrams.excalidraw
file located next to thisREADME.md
- Make your changes – follow the existing organizational structure with boxes for individual URLs
- Click the ☰ menu at the top left, select Save to...
- In the Save to disk section, set the file name as
goldsky-docs-diagrams
- Click Save to file
- Replace the
goldsky-docs-diagrams.excalidraw
file next to thisREADME.md
with the file you saved in the previous step
For each diagram, we keep light and dark mode versions. To export a diagram from the Excalidraw canvas:
- Follow the steps above to open the
goldsky-docs-diagrams.excalidraw
in Excalidraw - Select the parts of the canvas you want to export
- Click the ☰ menu at the top left, select Export image...
- Alternatively, press Ctrl/Cmd + E on the canvas
- Set the following settings:
- Background
- Only selected
- Embed scene
- 2x scale
- A File name that matches the existing naming pattern in
./public/images/docs/**/*.png
, ending in either-dark.png
or-light.png
depending on the theme you selected
- Click the PNG button to export the diagram
- Repeat the above process, but with the opposite theme (i.e. use dark mode if you exported light mode before)
- To change the theme, click the moon or sun icon at the bottom right corner of the export dialog
- Open the Markdown documentation file where you want to integrate the diagram
- Use the following code snippet to display the diagram:
Note: The
{% excalidraw src="/images/docs/.../goldsky-..." alt="..." width="200" height="240" /%}
src
attribute does not include the-light.png
or-dark.png
suffix, this will be added depending on the preferred theme when a visitor looks at the deployed documentation web application.
To learn more about the technologies used in this documentation web app, see the following resources:
- Tailwind CSS - the official Tailwind CSS documentation
- Next.js - the official Next.js documentation
- Headless UI - the official Headless UI documentation
- Markdoc - the official Markdoc documentation
- DocSearch - the official DocSearch documentation