From 147bf4dc2ddcb83b5aeadd3068ef949920545a60 Mon Sep 17 00:00:00 2001 From: Richard Harris Date: Sun, 10 Mar 2019 23:11:25 -0400 Subject: [PATCH] start planning API reference docs --- site/content/docs/00-introduction.md | 9 ++ site/content/docs/99-outline.md | 49 ++++++++ .../_old_docs}/02-template-syntax.md | 0 .../_old_docs}/03-scoped-styles.md | 0 .../{guide => docs/_old_docs}/04-behaviour.md | 0 .../_old_docs}/05-nested-components.md | 0 .../_old_docs}/06-special-components.md | 0 .../{guide => docs/_old_docs}/07-events.md | 0 .../{guide => docs/_old_docs}/08-bindings.md | 0 .../_old_docs}/09-transitions.md | 0 .../{guide => docs/_old_docs}/10-actions.md | 0 .../{guide => docs/_old_docs}/11-classes.md | 0 .../_old_docs}/14-module-context.md | 0 .../_old_docs}/15-server-side-rendering.md | 0 .../_old_docs}/16-state-management.md | 0 .../_old_docs}/17-preprocessing.md | 0 .../{guide => docs/_old_docs}/18-advanced.md | 0 .../_old_docs}/19-custom-elements.md | 0 .../_old_docs}/20-miscellaneous.md | 0 .../_old_docs}/98-api-reference.md | 0 .../_old_docs}/99-still-to-come.md | 0 site/content/guide/0-important-note.md | 7 -- site/content/guide/00-introduction.md | 112 ------------------ .../blog/[slug].js => blog/[slug].json.js} | 0 site/src/routes/blog/[slug].svelte | 2 +- site/src/routes/{api => }/blog/_posts.js | 2 +- .../{api/blog/index.js => blog/index.json.js} | 0 site/src/routes/blog/index.svelte | 2 +- site/src/routes/blog/rss.xml.js | 2 +- site/src/routes/docs/_GuideContents.svelte | 4 +- site/src/routes/docs/_sections.js | 61 +--------- site/src/routes/docs/demo/[hash].json.js | 22 ---- site/src/routes/docs/index.svelte | 28 ++--- site/src/routes/index.svelte | 2 +- 34 files changed, 81 insertions(+), 221 deletions(-) create mode 100644 site/content/docs/00-introduction.md create mode 100644 site/content/docs/99-outline.md rename site/content/{guide => docs/_old_docs}/02-template-syntax.md (100%) rename site/content/{guide => docs/_old_docs}/03-scoped-styles.md (100%) rename site/content/{guide => docs/_old_docs}/04-behaviour.md (100%) rename site/content/{guide => docs/_old_docs}/05-nested-components.md (100%) rename site/content/{guide => docs/_old_docs}/06-special-components.md (100%) rename site/content/{guide => docs/_old_docs}/07-events.md (100%) rename site/content/{guide => docs/_old_docs}/08-bindings.md (100%) rename site/content/{guide => docs/_old_docs}/09-transitions.md (100%) rename site/content/{guide => docs/_old_docs}/10-actions.md (100%) rename site/content/{guide => docs/_old_docs}/11-classes.md (100%) rename site/content/{guide => docs/_old_docs}/14-module-context.md (100%) rename site/content/{guide => docs/_old_docs}/15-server-side-rendering.md (100%) rename site/content/{guide => docs/_old_docs}/16-state-management.md (100%) rename site/content/{guide => docs/_old_docs}/17-preprocessing.md (100%) rename site/content/{guide => docs/_old_docs}/18-advanced.md (100%) rename site/content/{guide => docs/_old_docs}/19-custom-elements.md (100%) rename site/content/{guide => docs/_old_docs}/20-miscellaneous.md (100%) rename site/content/{guide => docs/_old_docs}/98-api-reference.md (100%) rename site/content/{guide => docs/_old_docs}/99-still-to-come.md (100%) delete mode 100644 site/content/guide/0-important-note.md delete mode 100644 site/content/guide/00-introduction.md rename site/src/routes/{api/blog/[slug].js => blog/[slug].json.js} (100%) rename site/src/routes/{api => }/blog/_posts.js (93%) rename site/src/routes/{api/blog/index.js => blog/index.json.js} (100%) delete mode 100644 site/src/routes/docs/demo/[hash].json.js diff --git a/site/content/docs/00-introduction.md b/site/content/docs/00-introduction.md new file mode 100644 index 0000000000..6766d5c968 --- /dev/null +++ b/site/content/docs/00-introduction.md @@ -0,0 +1,9 @@ +--- +title: Before we begin +--- + +> Temporary note: This document is a work-in-progress. Please forgive any missing or misleading parts, and don't be shy about asking for help in the [Discord chatroom](https://discord.gg/yy75DKs). The [tutorial](https://discord.gg/yy75DKs) is more complete; start there. + +This page contains detailed API reference documentation. It's intended to be a resource for people who already have some familiarity with Svelte. + +If that's not you (yet), you may prefer to visit the [interactive tutorial](tutorial) or the [examples](examples) before consulting this reference. \ No newline at end of file diff --git a/site/content/docs/99-outline.md b/site/content/docs/99-outline.md new file mode 100644 index 0000000000..f53bb2c784 --- /dev/null +++ b/site/content/docs/99-outline.md @@ -0,0 +1,49 @@ +--- +title: Outline +--- + +(This isn't the actual documentation, this is just me getting my thoughts straight so that we can create the documentation.) + +I think it makes sense to split the docs into compile time (`svelte.preprocess` and `svelte.compile`), then run time (component API, `svelte`, `svelte/store`, `svelte/motion`, etc). I'm not sure where template syntax, style scoping (and `:global(...)`), `context="module"` etc goes. + +### Compile time + +* `const preprocessed = await svelte.preprocess(source, options);` +* `const result = svelte.compile(source, options);` + + +### Run time + +#### Client-side component API + +* `const component = new Component(options);` +* `component.$set(...);` +* `component.$on(event, callback);` +* `component.$destroy();` +* `component.x` if `accessors: true` + + +#### Server-side component API + +* `const result = Component.render(...)` + + +#### svelte + +* lifecycle methods, tick, context +* SSR behaviour + + +#### svelte/store + +* writable, readable, derive, get + +#### svelte/motion + +* spring, tweened + +#### svelte/transition + +#### svelte/animation (TODO make this) + +#### svelte/easing \ No newline at end of file diff --git a/site/content/guide/02-template-syntax.md b/site/content/docs/_old_docs/02-template-syntax.md similarity index 100% rename from site/content/guide/02-template-syntax.md rename to site/content/docs/_old_docs/02-template-syntax.md diff --git a/site/content/guide/03-scoped-styles.md b/site/content/docs/_old_docs/03-scoped-styles.md similarity index 100% rename from site/content/guide/03-scoped-styles.md rename to site/content/docs/_old_docs/03-scoped-styles.md diff --git a/site/content/guide/04-behaviour.md b/site/content/docs/_old_docs/04-behaviour.md similarity index 100% rename from site/content/guide/04-behaviour.md rename to site/content/docs/_old_docs/04-behaviour.md diff --git a/site/content/guide/05-nested-components.md b/site/content/docs/_old_docs/05-nested-components.md similarity index 100% rename from site/content/guide/05-nested-components.md rename to site/content/docs/_old_docs/05-nested-components.md diff --git a/site/content/guide/06-special-components.md b/site/content/docs/_old_docs/06-special-components.md similarity index 100% rename from site/content/guide/06-special-components.md rename to site/content/docs/_old_docs/06-special-components.md diff --git a/site/content/guide/07-events.md b/site/content/docs/_old_docs/07-events.md similarity index 100% rename from site/content/guide/07-events.md rename to site/content/docs/_old_docs/07-events.md diff --git a/site/content/guide/08-bindings.md b/site/content/docs/_old_docs/08-bindings.md similarity index 100% rename from site/content/guide/08-bindings.md rename to site/content/docs/_old_docs/08-bindings.md diff --git a/site/content/guide/09-transitions.md b/site/content/docs/_old_docs/09-transitions.md similarity index 100% rename from site/content/guide/09-transitions.md rename to site/content/docs/_old_docs/09-transitions.md diff --git a/site/content/guide/10-actions.md b/site/content/docs/_old_docs/10-actions.md similarity index 100% rename from site/content/guide/10-actions.md rename to site/content/docs/_old_docs/10-actions.md diff --git a/site/content/guide/11-classes.md b/site/content/docs/_old_docs/11-classes.md similarity index 100% rename from site/content/guide/11-classes.md rename to site/content/docs/_old_docs/11-classes.md diff --git a/site/content/guide/14-module-context.md b/site/content/docs/_old_docs/14-module-context.md similarity index 100% rename from site/content/guide/14-module-context.md rename to site/content/docs/_old_docs/14-module-context.md diff --git a/site/content/guide/15-server-side-rendering.md b/site/content/docs/_old_docs/15-server-side-rendering.md similarity index 100% rename from site/content/guide/15-server-side-rendering.md rename to site/content/docs/_old_docs/15-server-side-rendering.md diff --git a/site/content/guide/16-state-management.md b/site/content/docs/_old_docs/16-state-management.md similarity index 100% rename from site/content/guide/16-state-management.md rename to site/content/docs/_old_docs/16-state-management.md diff --git a/site/content/guide/17-preprocessing.md b/site/content/docs/_old_docs/17-preprocessing.md similarity index 100% rename from site/content/guide/17-preprocessing.md rename to site/content/docs/_old_docs/17-preprocessing.md diff --git a/site/content/guide/18-advanced.md b/site/content/docs/_old_docs/18-advanced.md similarity index 100% rename from site/content/guide/18-advanced.md rename to site/content/docs/_old_docs/18-advanced.md diff --git a/site/content/guide/19-custom-elements.md b/site/content/docs/_old_docs/19-custom-elements.md similarity index 100% rename from site/content/guide/19-custom-elements.md rename to site/content/docs/_old_docs/19-custom-elements.md diff --git a/site/content/guide/20-miscellaneous.md b/site/content/docs/_old_docs/20-miscellaneous.md similarity index 100% rename from site/content/guide/20-miscellaneous.md rename to site/content/docs/_old_docs/20-miscellaneous.md diff --git a/site/content/guide/98-api-reference.md b/site/content/docs/_old_docs/98-api-reference.md similarity index 100% rename from site/content/guide/98-api-reference.md rename to site/content/docs/_old_docs/98-api-reference.md diff --git a/site/content/guide/99-still-to-come.md b/site/content/docs/_old_docs/99-still-to-come.md similarity index 100% rename from site/content/guide/99-still-to-come.md rename to site/content/docs/_old_docs/99-still-to-come.md diff --git a/site/content/guide/0-important-note.md b/site/content/guide/0-important-note.md deleted file mode 100644 index ae751e1f93..0000000000 --- a/site/content/guide/0-important-note.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Important note ---- - -### Read the RFCs - -Much of the documentation below is out of date! For more accurate and current information on how Svelte 3 works in the meantime, check out the RFCS on [reactive assignments](https://github.com/sveltejs/rfcs/blob/master/text/0001-reactive-assignments.md), [reactive stores](https://github.com/sveltejs/rfcs/blob/master/text/0002-reactive-stores.md) and [reactive declarations](https://github.com/sveltejs/rfcs/blob/master/text/0003-reactive-declarations.md). diff --git a/site/content/guide/00-introduction.md b/site/content/guide/00-introduction.md deleted file mode 100644 index ea28d2faf0..0000000000 --- a/site/content/guide/00-introduction.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Introduction ---- - -### What is Svelte? - -Svelte is a tool for building fast web applications. - -It is similar to JavaScript frameworks such as React and Vue, which share a goal of making it easy to build slick interactive user interfaces. - -But there's a crucial difference: Svelte converts your app into ideal JavaScript at *build time*, rather than interpreting your application code at *run time*. This means you don't pay the performance cost of the framework's abstractions, and you don't incur a penalty when your app first loads. - -You can build your entire app with Svelte, or you can add it incrementally to an existing codebase. You can also ship components as standalone packages that work anywhere, without the overhead of a dependency on a conventional framework. - -[Read the introductory blog post](/blog/frameworks-without-the-framework) to learn more about Svelte's goals and philosophy. - - -### Understanding components - -In Svelte, an application is composed from one or more *components*. A component is a reusable self-contained block of code that encapsulates markup, styles and behaviours that belong together, written into an `.html` file. Here's a simple example: - -```html - -

Hello {name}!

-``` - -```json -/* { hidden: true } */ -{ - name: 'world' -} -``` - -> Wherever you see REPL links, click through for an interactive example - -Svelte turns this into a JavaScript module that you can import into your app: - -```js -/* { filename: 'main.js' } */ -import App from './App.html'; - -const app = new App({ - target: document.querySelector('main'), - props: { name: 'world' }, -}); - -// change the component's "name" prop. We'll learn about props (aka properties) below -app.name = 'everybody'; - -// detach the component and clean everything up -app.$destroy(); -``` - -Congratulations, you've just learned about half of Svelte's API! - - -### Getting started - -Normally, this is the part where the instructions might tell you to add the framework to your page as a ` diff --git a/site/src/routes/api/blog/_posts.js b/site/src/routes/blog/_posts.js similarity index 93% rename from site/src/routes/api/blog/_posts.js rename to site/src/routes/blog/_posts.js index 33c033b517..3b6ec37dab 100644 --- a/site/src/routes/api/blog/_posts.js +++ b/site/src/routes/blog/_posts.js @@ -1,6 +1,6 @@ import fs from 'fs'; import path from 'path'; -import { extract_frontmatter, langs } from '../../../utils/markdown.js'; +import { extract_frontmatter, langs } from '../../utils/markdown.js'; import marked from 'marked'; import PrismJS from 'prismjs'; import 'prismjs/components/prism-bash'; diff --git a/site/src/routes/api/blog/index.js b/site/src/routes/blog/index.json.js similarity index 100% rename from site/src/routes/api/blog/index.js rename to site/src/routes/blog/index.json.js diff --git a/site/src/routes/blog/index.svelte b/site/src/routes/blog/index.svelte index 86828e42ca..a8bffc9b5d 100644 --- a/site/src/routes/blog/index.svelte +++ b/site/src/routes/blog/index.svelte @@ -1,6 +1,6 @@ diff --git a/site/src/routes/blog/rss.xml.js b/site/src/routes/blog/rss.xml.js index 135e70499f..5b0da33cfe 100644 --- a/site/src/routes/blog/rss.xml.js +++ b/site/src/routes/blog/rss.xml.js @@ -1,4 +1,4 @@ -import get_posts from '../api/blog/_posts.js'; +import get_posts from '../blog/_posts.js'; const months = ',Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec'.split(','); diff --git a/site/src/routes/docs/_GuideContents.svelte b/site/src/routes/docs/_GuideContents.svelte index 6fc7c6c588..e7e5c08551 100644 --- a/site/src/routes/docs/_GuideContents.svelte +++ b/site/src/routes/docs/_GuideContents.svelte @@ -72,7 +72,7 @@ - Learn Svelte + API Docs • Svelte
{#each sections as section} -
-

- - - - {section.metadata.title} - - - - -

- {@html section.html} -
+
+

+ + + + {section.metadata.title} + + + + +

+ {@html section.html} +
{/each}
diff --git a/site/src/routes/index.svelte b/site/src/routes/index.svelte index edde4372c6..60eaee392a 100644 --- a/site/src/routes/index.svelte +++ b/site/src/routes/index.svelte @@ -222,7 +222,7 @@ npm run dev & open http://localhost:5000

See the quickstart guide for more information.

-

Learn Svelte

+

Learn Svelte