goldsky-io / docs-v1

Goldsky documentation

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.

To Preview

1. Clone the repository to your local machine using git clone https://github.com/goldsky/docs.git
2. Navigate to the cloned repository using cd docs
3. Install the necessary dependencies using npm install
4. Start the local development server using npm run dev
5. Open your web browser and navigate to http://localhost:3000 to preview the documentation.

Diagrams

Diagrams are part of a single Excalidraw canvas.

Add a new diagram / modify an existing one

To create a new diagram or edit an existing one:

1. Navigate to https://excalidraw.com
2. Click the ☰ menu at the top left, select Open
   • Alternatively, press Ctrl/Cmd + O on the canvas
3. Select the goldsky-docs-diagrams.excalidraw file located next to this README.md
4. Make your changes – follow the existing organizational structure with boxes for individual URLs
5. Click the ☰ menu at the top left, select Save to...
6. In the Save to disk section, set the file name as goldsky-docs-diagrams
7. Click Save to file
8. Replace the goldsky-docs-diagrams.excalidraw file next to this README.md with the file you saved in the previous step

Integrate a diagram into the docs

For each diagram, we keep light and dark mode versions. To export a diagram from the Excalidraw canvas:

1. Follow the steps above to open the goldsky-docs-diagrams.excalidraw in Excalidraw
2. Select the parts of the canvas you want to export
3. Click the ☰ menu at the top left, select Export image...
   • Alternatively, press Ctrl/Cmd + E on the canvas
4. 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
5. Click the PNG button to export the diagram
6. 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
7. Open the Markdown documentation file where you want to integrate the diagram
8. Use the following code snippet to display the diagram:

   {% excalidraw
     src="/images/docs/.../goldsky-..."
     alt="..."
     width="200"
     height="240"
   /%}
   

   Note: The 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.

Learn more

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