diff --git a/astro.config.mjs b/astro.config.mjs index ea3595e..6296886 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -16,10 +16,22 @@ export default defineConfig({ }, sidebar: [ { - label: 'Guides', + label: 'Concepts', + items: [ + { label: 'Intro to GraphRAG', link: '/explanation/intro/' }, + ], + }, + { + label: 'Tutorials', items: [ // Each item here is one entry in the navigation menu. - { label: 'Intro to GraphRAG', link: '/guides/intro/' }, + { label: 'Chat with a PDF', link: '/tutorials/chat-with-pdf/' }, + ], + }, + { + label: 'How-to Guides', + items: [ + { label: 'Chunking', link: '/guides/chunking/' }, ], }, { @@ -30,7 +42,11 @@ export default defineConfig({ autogenerate: { directory: 'reference/graphrag' }, }, { - label: 'Graph Patterns', + label: 'Data Preparation', + autogenerate: { directory: 'reference/preparation' }, + }, + { + label: 'Graph Shapes', autogenerate: { directory: 'reference/knowledge-graph' }, } ] diff --git a/media/diagram-template.excalidraw b/media/diagram-template.excalidraw new file mode 100644 index 0000000..1f9672a --- /dev/null +++ b/media/diagram-template.excalidraw @@ -0,0 +1,86 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "3MMtvnlqtdgj1Cnckb_s-", + "type": "rectangle", + "x": 440, + "y": 255, + "width": 494, + "height": 200, + "angle": 0, + "strokeColor": "#1e1e1e", + "backgroundColor": "#a5d8ff", + "fillStyle": "hachure", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 2, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a0", + "roundness": { + "type": 3 + }, + "seed": 1812761710, + "version": 50, + "versionNonce": 1925151534, + "isDeleted": false, + "boundElements": [ + { + "type": "text", + "id": "q_Og5WG56EY8BmiTtfJOO" + } + ], + "updated": 1724761641841, + "link": null, + "locked": false + }, + { + "id": "q_Og5WG56EY8BmiTtfJOO", + "type": "text", + "x": 598.6600036621094, + "y": 342.5, + "width": 176.67999267578125, + "height": 25, + "angle": 0, + "strokeColor": "#1e1e1e", + "backgroundColor": "#a5d8ff", + "fillStyle": "hachure", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 2, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a1", + "roundness": null, + "seed": 45417714, + "version": 21, + "versionNonce": 210700722, + "isDeleted": false, + "boundElements": null, + "updated": 1724761646797, + "link": null, + "locked": false, + "text": "Diagram goes here", + "fontSize": 20, + "fontFamily": 5, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": "3MMtvnlqtdgj1Cnckb_s-", + "originalText": "Diagram goes here", + "autoResize": true, + "lineHeight": 1.25 + } + ], + "appState": { + "gridSize": 20, + "gridStep": 5, + "gridModeEnabled": false, + "viewBackgroundColor": "#ffffff" + }, + "files": {} +} \ No newline at end of file diff --git a/src/assets/images/diagram-template.svg b/src/assets/images/diagram-template.svg new file mode 100644 index 0000000..cd7c16e --- /dev/null +++ b/src/assets/images/diagram-template.svg @@ -0,0 +1,13 @@ + + + + + + + + Diagram goes here \ No newline at end of file diff --git a/src/content/docs/explanation/index.md b/src/content/docs/explanation/index.md new file mode 100644 index 0000000..07e26fd --- /dev/null +++ b/src/content/docs/explanation/index.md @@ -0,0 +1,10 @@ +--- +title: Explanations +description: High-level concepts, independent of technical implementation or applied context +--- + +## Explanations + +- [Intro to GraphRAG](/explanation/intro/) - +- [Knowledge Graph](/explanation/knowledge-graph/) - + diff --git a/src/content/docs/explanation/intro.md b/src/content/docs/explanation/intro.md new file mode 100644 index 0000000..6ca8493 --- /dev/null +++ b/src/content/docs/explanation/intro.md @@ -0,0 +1,10 @@ +--- +title: Intro to GraphRAG +description: RAG with a knowledge graph +--- + +![GraphRAG Overview](../../../assets/images/diagram-template.svg) + +## Further reading + +- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/src/content/docs/explanation/template.md b/src/content/docs/explanation/template.md new file mode 100644 index 0000000..8e77705 --- /dev/null +++ b/src/content/docs/explanation/template.md @@ -0,0 +1,47 @@ +--- +title: (Explanation Template) +description: Make a copy of this to create a new explanation +--- + + + +![GraphRAG Overview](../../../assets/images/diagram-template.svg) + +**Instructions**: + +1. Create a diagram using https://excalidraw.com +2. Save the Excalidraw file in `/media` +3. Save an SVG export of the diagram in `/src/assets/images` +4. Link to it above using a relative path + +## About (Explanation) + +**Instructions**: + +1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post + +An Explanation deepens and broadens the reader’s understanding of a subject. It brings clarity, light and context. + +Explanation - understanding oriented, theoretical knowledge, that serves our study +The concept of reflection is important. Reflection occurs after something else, and depends on something else, yet at the same time brings something new - shines a new light - on the subject matter. + +The perspective of explanation is higher and wider than that of the other not types. It does not take the user’s eye-level view, as in a how-to guide, or a close-up view of the machinery, like reference material. Its scope in each case is a topic - “an area of knowledge”, that somehow has to be bounded in a reasonable, meaningful way. + +Explanations motivate why things are the way they are. + +## Detailed (Explanation) + +**Instructions**: + +1. Add extra sections delving deeper into the topic + +. + +**Further reading**: + +**Instructions**: + +1. Provide links to external sources +2. Don't keep the link below, it's for your reference as the author + +- Read [about explanations](https://diataxis.fr/explanation/) in the Diátaxis framework diff --git a/src/content/docs/guides/index.md b/src/content/docs/guides/index.md new file mode 100644 index 0000000..74c8f9b --- /dev/null +++ b/src/content/docs/guides/index.md @@ -0,0 +1,11 @@ +--- +title: How-to Guides +description: A reference page in my new Starlight docs site. +--- + +A how-to guide helps the user get something done, correctly and safely; it guides the user’s action. + +It’s concerned with work - navigating from one side to the other of a real-world problem-field. +## Further reading + +- Read [about guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/src/content/docs/guides/template.md b/src/content/docs/guides/template.md new file mode 100644 index 0000000..47394be --- /dev/null +++ b/src/content/docs/guides/template.md @@ -0,0 +1,43 @@ +--- +title: (How-to Template) +description: Make a copy of this to create a new how-to guide +--- + + + +![GraphRAG Overview](../../../assets/images/diagram-template.svg) + +**Instructions**: + +1. Create a diagram using https://excalidraw.com +2. Save the Excalidraw file in `/media` +3. Save an SVG export of the diagram in `/src/assets/images` +4. Link to it above using a relative path + +## About (How-to guide) + +**Instructions**: + +1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post + +A how-to guide helps the user get something done, correctly and safely; it guides the user’s action. + +It’s concerned with work - navigating from one side to the other of a real-world problem-field. + +How-to guides describe how to do accomplish some goal. + +## Detailed (How-to) + +**Instructions**: + +1. Add extra sections with step-by-step directions +2. Avoid implementation specific details (programming language or framework -specific) + +**Further reading**: + +**Instructions**: + +1. Provide links to external sources +2. Don't keep the link below, it's for your reference as the author + +- Read [about guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/src/content/docs/reference/kg.md b/src/content/docs/reference/index.md similarity index 93% rename from src/content/docs/reference/kg.md rename to src/content/docs/reference/index.md index 0224f09..5ab9c61 100644 --- a/src/content/docs/reference/kg.md +++ b/src/content/docs/reference/index.md @@ -1,5 +1,5 @@ --- -title: Example Reference +title: Reference Material description: A reference page in my new Starlight docs site. --- diff --git a/src/content/docs/guides/ner.md b/src/content/docs/reference/preparation/ner.md similarity index 100% rename from src/content/docs/guides/ner.md rename to src/content/docs/reference/preparation/ner.md diff --git a/src/content/docs/reference/template.md b/src/content/docs/reference/template.md new file mode 100644 index 0000000..aa03a84 --- /dev/null +++ b/src/content/docs/reference/template.md @@ -0,0 +1,42 @@ +--- +title: (Reference Template) +description: Make a copy of this to create new reference material +--- + + + +![GraphRAG Overview](../../../assets/images/diagram-template.svg) + +**Instructions**: + +1. Create a diagram using https://excalidraw.com +2. Save the Excalidraw file in `/media` +3. Save an SVG export of the diagram in `/src/assets/images` +4. Link to it above using a relative path + +## About (Reference) + +**Instructions**: + +1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post + +Reference material is ideal for outlining how things work in terse and clear terms. +Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. + +Reference material describes what something is. + +## Detailed (How-to) + +**Instructions**: + +1. Add extra sections with step-by-step directions +2. Avoid implementation specific details (programming language or framework -specific) + +**Further reading**: + +**Instructions**: + +1. Provide links to external sources +2. Don't keep the link below, it's for your reference as the author + +- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/src/content/docs/guides/intro.md b/src/content/docs/tutorials/chat-with-pdf.md similarity index 100% rename from src/content/docs/guides/intro.md rename to src/content/docs/tutorials/chat-with-pdf.md diff --git a/src/content/docs/tutorials/index.md b/src/content/docs/tutorials/index.md new file mode 100644 index 0000000..3675cfa --- /dev/null +++ b/src/content/docs/tutorials/index.md @@ -0,0 +1,17 @@ +--- +title: GraphRAG Tutorials +description: A reference page in my new Starlight docs site. +--- + +## About Tutorials + +A tutorial is a practical activity, in which the student learns by doing something meaningful, towards some achievable goal. + +A tutorial serves the user’s acquisition of skills and knowledge - their study. Its purpose is not to help the user get something done, but to help them learn. + +Tutorials - learning-oriented guides that describe practical steps and are intended to serve our study. +A tutorial in other words is a lesson. + +*Further reading*: + +- Read [about tutorials](https://diataxis.fr/tutorials/) in the Diátaxis framework diff --git a/src/content/docs/tutorials/template.md b/src/content/docs/tutorials/template.md new file mode 100644 index 0000000..e393893 --- /dev/null +++ b/src/content/docs/tutorials/template.md @@ -0,0 +1,44 @@ +--- +title: (Tutorial template) +description: Make a copy of this to create new tutorital +--- + + + +![Tutorial diagram](../../../assets/images/diagram-template.svg) + +**Instructions**: + +1. Create a diagram using https://excalidraw.com +2. Save the Excalidraw file in `/media` +3. Save an SVG export of the diagram in `/src/assets/images` +4. Link to it above using a relative path + +## About (Tutorial) + +**Instructions**: + +1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post + +A tutorial is a practical activity, in which the student learns by doing something meaningful, towards some achievable goal. + +A tutorial serves the user’s acquisition of skills and knowledge - their study. Its purpose is not to help the user get something done, but to help them learn. + +Tutorials - learning-oriented guides that describe practical steps and are intended to serve our study. +A tutorial in other words is a lesson. They apply how-tos into a practical solution. + +## Detailed (Tutorial) + +**Instructions**: + +1. Add extra sections that outline a complete solution + +**Further reading**: + +**Instructions**: + +1. Provide links to external sources +2. Link to relevant how-tos and reference material used in the tutorial +3. Don't keep the link below, it's for your reference as the author + +- Read [about tutorials](https://diataxis.fr/tutorials/) in the Diátaxis framework