diff --git a/README.md b/README.md index c66e354..3e9c27d 100644 --- a/README.md +++ b/README.md @@ -2,144 +2,4 @@ Based on [Astro Starter Kit: Docs Site](https://github.com/ccutch/biplane) -## Commands Cheatsheet - -All commands are run from the root of the project, from a terminal: - -| Command | Action | -| :--------------------- | :----------------------------------------------- | -| `npm install` | Installs dependencies | -| `npm run dev` | Starts local dev server at `localhost:3000` | -| `npm run build` | Build your production site to `./dist/` | -| `npm run preview` | Preview your build locally, before deploying | -| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | -| `npm run astro --help` | Get help using the Astro CLI | - -## New to Astro? - -Welcome! Check out [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat). - -## Customize This Theme - -### Site metadata - -`src/config.ts` contains several data objects that describe metadata about your site like title, description, default language, and Open Graph details. You can customize these to match your project. - -### CSS styling - -The theme's look and feel is controlled by a few key variables that you can customize yourself. You'll find them in the `src/styles/theme.css` CSS file. - -If you've never worked with CSS variables before, give [MDN's guide on CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) a quick read. - -This theme uses a "cool blue" accent color by default. To customize this for your project, change the `--theme-accent` variable to whatever color you'd like: - -```diff -/* src/styles/theme.css */ -:root { - color-scheme: light; -- --theme-accent: hsla(var(--color-blue), 1); -+ --theme-accent: hsla(var(--color-red), 1); /* or: hsla(#FF0000, 1); */ -``` - -## Page metadata - -Astro uses frontmatter in Markdown pages to choose layouts and pass properties to those layouts. If you are using the default layout, you can customize the page in many different ways to optimize SEO and other things. For example, you can use the `title` and `description` properties to set the document title, meta title, meta description, and Open Graph description. - -```markdown ---- -title: Example title -description: Really cool docs example that uses Astro -layout: ../../layouts/MainLayout.astro ---- - -# Page content... -``` - -For more SEO related properties, look at `src/components/HeadSEO.astro` - -### Sidebar navigation - -The sidebar navigation is controlled by the `SIDEBAR` variable in your `src/config.ts` file. You can customize the sidebar by modifying this object. A default, starter navigation has already been created for you. - -```ts -export const SIDEBAR = { - en: [ - { text: "Section Header", header: true }, - { text: "Introduction", link: "en/introduction" }, - { text: "Page 2", link: "en/page-2" }, - { text: "Page 3", link: "en/page-3" }, - - { text: "Another Section", header: true }, - { text: "Page 4", link: "en/page-4" }, - ], -}; -``` - -Note the top-level `en` key: This is needed for multi-language support. You can change it to whatever language you'd like, or add new languages as you go. More details on this below. - -### Multiple Languages support - -The Astro docs template supports multiple langauges out of the box. The default theme only shows `en` documentation, but you can enable multi-language support features by adding a second language to your project. - -To add a new language to your project, you'll want to extend the current `src/pages/[lang]/...` layout: - -```diff - πŸ“‚ src/pages - ┣ πŸ“‚ en - ┃ ┣ πŸ“œ page-1.md - ┃ ┣ πŸ“œ page-2.md - ┃ ┣ πŸ“œ page-3.astro -+ ┣ πŸ“‚ es -+ ┃ ┣ πŸ“œ page-1.md -+ ┃ ┣ πŸ“œ page-2.md -+ ┃ ┣ πŸ“œ page-3.astro -``` - -You'll also need to add the new language name to the `KNOWN_LANGUAGES` map in your `src/config.ts` file. This will enable your new language switcher in the site header. - -```diff -// src/config.ts -export const KNOWN_LANGUAGES = { - English: 'en', -+ Spanish: 'es', -}; -``` - -Last step: you'll need to add a new entry to your sidebar, to create the table of contents for that language. While duplicating every page might not sound ideal to everyone, this extra control allows you to create entirely custom content for every language. - -> Make sure the sidebar `link` value points to the correct language! - -```diff -// src/config.ts -export const SIDEBAR = { - en: [ - { text: 'Section Header', header: true, }, - { text: 'Introduction', link: 'en/introduction' }, - // ... - ], -+ es: [ -+ { text: 'Encabezado de secciΓ³n', header: true, }, -+ { text: 'IntroducciΓ³n', link: 'es/introduction' }, -+ // ... -+ ], -}; - -// ... -``` - -If you plan to use Spanish as the the default language, you just need to modify the redirect path in `src/pages/index.astro`: - -```diff - -``` - -You can also remove the above script and write a landing page in Spanish instead. - -### What if I don't plan to support multiple languages? - -That's totally fine! Not all projects need (or can support) multiple languages. You can continue to use this theme without ever adding a second language. - -If that single language is not English, you can just replace `en` in directory layouts and configurations with the preferred language. +Find the [documentation online here](https://docs.nextgraph.org) diff --git a/src/config.ts b/src/config.ts index 2c7f3b8..2dcf008 100644 --- a/src/config.ts +++ b/src/config.ts @@ -45,17 +45,61 @@ export type Sidebar = Record< >; export const SIDEBAR: Sidebar = { en: { - Guides: [ + "App & Platform": [ { text: "Introduction", link: "en/introduction" }, { text: "Getting started", link: "en/getting-started" }, + { text: "Local-First", link: "en/local-first" }, + { text: "Encryption", link: "en/encryption" }, + { text: "Wallet", link: "en/wallet" }, + { text: "Documents and Stores", link: "en/documents" }, + { text: "Social Network", link: "en/social-network" }, + { text: "Collaborative tools", link: "en/collaboration" }, + { text: "Features", link: "en/features" }, + { text: "Self-Hosted", link: "en/self-hosted" }, { text: "Help / FAQ", link: "en/help" }, { text: "Accessibility", link: "en/accessibility" }, + { text: "Roadmap", link: "en/roadmap" }, + ], + "Framework": [ + { text: "Introduction", link: "en/framework" }, + { text: "Getting started", link: "en/framework/getting-started" }, + { text: "Data-First", link: "en/framework/data-first"}, + { text: "CRDTs", link: "en/framework/crdts" }, + { text: "Semantic Web", link: "en/framework/semantic" }, + { text: "Schema", link: "en/framework/schema" }, + { text: "DID & NURI", link: "en/framework/nuri" }, + { text: "Transactions", link: "en/framework/transactions" }, + { text: "Permissions", link: "en/framework/permissions" }, + { text: "Smart-contract", link: "en/framework/smart-contract" }, + { text: "Ecosystem", link: "en/ecosystem" }, + { text: "ActivityPub", link: "en/activitypub" }, + { text: "Solid", link: "en/solid" }, + { text: "Roadmap", link: "en/framework/roadmap" }, ], Design: [ { text: "Overview", link: "en/design" }, - { text: "CRDTs", link: "en/crdts" }, + { text: "Architecture", link: "en/architecture" }, + { text: "Network", link: "en/network" }, + { text: "Sync Protocol", link: "en/protocol" }, + { text: "Verifier", link: "en/verifier" }, { text: "Specifications", link: "en/specs" }, + { text: "Security Audit", link: "en/audit" }, + { text: "Survey", link: "en/survey" }, + ], + "Reference": [ + { text: "NodeJS SDK", link: "en/nodejs" }, + { text: "Web JS SDK", link: "en/web" }, + { text: "Rust SDK", link: "en/rust" }, + { text: "Broker ngd", link: "en/ngd" }, + { text: "CLI", link: "en/cli" }, + { text: "Core protocol", link: "en/specs/protocol-core" }, + { text: "Client protocol", link: "en/specs/protocol-client" }, + { text: "App protocol", link: "en/specs/protocol-app" }, + { text: "Ext protocol", link: "en/specs/protocol-ext" }, + { text: "Admin protocol", link: "en/specs/protocol-admin" }, + { text: "Repo format", link: "en/specs/format-repo" }, + { text: "Wallet format", link: "en/specs/format-wallet" }, + { text: "DID method", link: "en/specs/did" }, ], - "API Reference": [{ text: "API", link: "en/api" }], }, }; diff --git a/src/pages/en/accessibility.md b/src/pages/en/accessibility.md index 978b7b5..49d2d5f 100644 --- a/src/pages/en/accessibility.md +++ b/src/pages/en/accessibility.md @@ -1,7 +1,5 @@ --- -title: Accessiblity -description: Accessiblity +title: Accessibility +description: Accessibility layout: ../../layouts/MainLayout.astro --- - -#### TODO diff --git a/src/pages/en/activitypub.md b/src/pages/en/activitypub.md new file mode 100644 index 0000000..7db73ba --- /dev/null +++ b/src/pages/en/activitypub.md @@ -0,0 +1,5 @@ +--- +title: ActivityPub compatibility +description: Interact with ActivityPub social networks from NextGraph, thanks to our collaboration with ActivityPods +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/api.md b/src/pages/en/api.md deleted file mode 100644 index 7244356..0000000 --- a/src/pages/en/api.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: API -description: NextGraph API -layout: ../../layouts/MainLayout.astro ---- - -#### TODO diff --git a/src/pages/en/architecture.md b/src/pages/en/architecture.md new file mode 100644 index 0000000..95fcb2c --- /dev/null +++ b/src/pages/en/architecture.md @@ -0,0 +1,5 @@ +--- +title: Architecture +description: General Architecture of NextGraph +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/audit.md b/src/pages/en/audit.md new file mode 100644 index 0000000..7b02b88 --- /dev/null +++ b/src/pages/en/audit.md @@ -0,0 +1,5 @@ +--- +title: Security Audit +description: NextGraph protocols and security claims have been audited +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/cli.md b/src/pages/en/cli.md new file mode 100644 index 0000000..44b8221 --- /dev/null +++ b/src/pages/en/cli.md @@ -0,0 +1,5 @@ +--- +title: CLI +description: Reference of the CLI of NextGraph +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/collaboration.md b/src/pages/en/collaboration.md new file mode 100644 index 0000000..ccce1b9 --- /dev/null +++ b/src/pages/en/collaboration.md @@ -0,0 +1,5 @@ +--- +title: Collaboration +description: Tools available for Collaboration and Productivity +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/design.md b/src/pages/en/design.md index 1da942f..f389532 100644 --- a/src/pages/en/design.md +++ b/src/pages/en/design.md @@ -3,11 +3,3 @@ title: Design description: NextGraph Design layout: ../../layouts/MainLayout.astro --- - -#### Design will be disclosed according to the roadmap. - -In the meanwhile, you can join the [forum](https://forum.nextgraph.org). - -And look at the code in our [Gitea instance](https://git.nextgraph.org/NextGraph). - -Stay tuned by subscribing to our [newsletter](https://list.nextgraph.org/subscription/form). diff --git a/src/pages/en/documents.md b/src/pages/en/documents.md new file mode 100644 index 0000000..65672d4 --- /dev/null +++ b/src/pages/en/documents.md @@ -0,0 +1,5 @@ +--- +title: Documents, Stores and Blocks +description: Organize your data with Documents, Stores, Branches and blocks +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/ecosystem.md b/src/pages/en/ecosystem.md new file mode 100644 index 0000000..6a66695 --- /dev/null +++ b/src/pages/en/ecosystem.md @@ -0,0 +1,5 @@ +--- +title: Ecosystem +description: Apps developed with NextGraph integrate its ecosystem +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/encryption.md b/src/pages/en/encryption.md new file mode 100644 index 0000000..752731b --- /dev/null +++ b/src/pages/en/encryption.md @@ -0,0 +1,5 @@ +--- +title: Encryption +description: End-to-End Encryption (E2EE) of all data in NextGraph, and encryption at rest too +layout: ../../layouts/MainLayout.astro +--- diff --git a/src/pages/en/features.md b/src/pages/en/features.md new file mode 100644 index 0000000..efdb2a5 --- /dev/null +++ b/src/pages/en/features.md @@ -0,0 +1,41 @@ +--- +title: Features +description: list of features available to all users in our native apps and web app +layout: ../../layouts/MainLayout.astro +--- + +### Official Apps + +Here is the list of types of Document you can create in NextGraph. In parenthesis is the type of underlying CRDT used by that type. See the [CRDTs](framework/crdts) article for more details about CRDTs. + +| Document type | Viewers | Editors | +| ------------------------ | ------------------ | ------------------ | +| Post or Article (YXml) | Post | Post Editor | +| | XML source | | +| Markdown (YXml) | Post | Post MD Editor | +| | Markdown source | | +| | XML source | | +| Plain Text (YText) | Text | Text Editor | +| Data / Graph (Graph) | Turtle | SPARQL Update | +| | SPARQL Query | | +| Data / Container (Graph) | Container (\*\*\*) | SPARQL Update | +| | Turtle | | +| | SPARQL Query | | +| Data / JSON (Automerge) | JSON (\*) | JSON Editor (\*) | +| | JSON source | | +| Data / Object (YMap) | JSON (\*\*) | JSON Editor (\*\*) | +| | JSON source | | +| Data / Array (YArray) | JSON (\*\*) | JSON Editor (\*\*) | +| | JSON source | | +| Code / Rust | Source Code | Text Editor | +| Code / JavaScript | Source Code | Text Editor | +| Code / TypeScript | Source Code | Text Editor | +| Code / Svelte | Source Code | Text Editor | +| Code / React | Source Code | Text Editor | + +Note: (\*) The JSON Editor (in read-write or read-only) is very primitive for now, it has been developed in one day, to showcase the easy binding of JSON data to some Svelte components. It lacks important features like ( insert in array at position. remove at position in array. splice range. remove from map. change type or name of property in map ). Also the general UX is ugly. But it is functional and demonstrate the potential of CRDT on JSON data, that will be leveraged by app developers. Once it will be improved, this Editor and Viewer will be reused for all Data types, including the Yjs based ones, and the Graph one. + +Note: (\*\*) The JSON Editor (in read-write or read-only) used here for the Yjs types, is based on svelte-jsoneditor which isn't so easy to use. But it is a good demonstration that the GUIs can be anything. The data layer works fine and that's the most important for now. + +Note: (\*\*\*) Containers are used for the Public Store, Protected Store and Private Store homepages. +Please note that apart from those 3 stores, creating new containers is not really useful yet as you have to add the triple `ldp:contains` manually with SPARQL Update if you want any document to be part of the container. diff --git a/src/pages/en/framework.md b/src/pages/en/framework.md new file mode 100644 index 0000000..3772b1b --- /dev/null +++ b/src/pages/en/framework.md @@ -0,0 +1,17 @@ +--- +title: Framework +description: Build decentralized, local-first and privacy-preserving apps +layout: ../../layouts/MainLayout.astro +--- + +NextGraph Framework will be available soon. + +Stay tuned! + +If you have questions or want to get in touch with us, the simplest way is to join the [forum](https://forum.nextgraph.org). + +For bug reports, please create an account and submit a new issue in our [Gitea instance](https://git.nextgraph.org/NextGraph). + +Stay tuned by subscribing to our [newsletter](https://list.nextgraph.org/subscription/form). + +Permissive license (MIT and Apache2) diff --git a/src/pages/en/crdts.md b/src/pages/en/framework/crdts.md similarity index 79% rename from src/pages/en/crdts.md rename to src/pages/en/framework/crdts.md index 5d2f44e..ceb1e3b 100644 --- a/src/pages/en/crdts.md +++ b/src/pages/en/framework/crdts.md @@ -1,7 +1,7 @@ --- title: Conflict-Free Replicated Data Types (CRDT) description: NextGraph supports several CRDTs natively, and is open to integrating more of them in the future. more about the Unified data model and features of our CRDTs -layout: ../../layouts/MainLayout.astro +layout: ../../../layouts/MainLayout.astro ---