From d00eeb7bdd9ae40686b5a8ab2707f042067dbac4 Mon Sep 17 00:00:00 2001 From: Taylor Hunt Date: Fri, 4 Nov 2022 17:16:01 -0400 Subject: [PATCH] Embetteren README (#216) - Logical heading structure, stronger hyperlink text, and better `alt` text for screen-readers (and all users in general, but especially screen-readers) - Tightened up language for succinctness and hopefully clarity - Formatting improvements --- packages/serve/README.md | 208 +++++++++++++++++++++------------------ 1 file changed, 110 insertions(+), 98 deletions(-) diff --git a/packages/serve/README.md b/packages/serve/README.md index 0ffa113..3d62cd3 100644 --- a/packages/serve/README.md +++ b/packages/serve/README.md @@ -1,28 +1,29 @@ -

- -
- @marko/serve -
- - - - API Stability - - - - NPM Version - - - - Downloads - -

- -When you serve a directory, every `.marko` file in that directory becomes a page. A browser is automatically launched and live-reloads as you make changes. It's the simplicity of a static file server plus the power of the Marko UI language. - -# Features - -- 🚀 Fastest way to build an app with Marko +
+

+ + @marko/serve 🍦 +

+

+ + + API Stability + + + + Latest NPM Version + + + + # of Weekly Downloads + +

+
+ +When you `serve` a directory, every `.marko` file in that directory becomes a page. A browser is automatically launched and live-reloads as you make changes. It's the simplicity of a static file server plus the power of [the Marko UI language](https://markojs.com/). + +## Features + +- 🚀 Fastest way to build a Marko app - 💖 No need to configure webpack, babel, etc. - ⚡️ Pages live-reload as you make changes - 📁 Directory-based routes @@ -39,147 +40,158 @@ And when you [`build`](../build/README.md) your production-ready app: - 🔮 Option to [pre-render]() to static HTML (great for GitHub Pages, Netlify, etc.) --> -# Getting Started +## Getting Started -## Hello World +### Hello World -To get started, let's create a new directory and serve it using `npx` (requires npm 5.2.0+): +Start by creating and entering a new directory, then serve it [using `npx`](https://docs.npmjs.com/cli/commands/npx) (requires npm 5.2.0+): -```bash +```sh mkdir my-new-app -cd my-new-app +cd my-new-app/ npx @marko/serve . ``` -When you serve a directory, a browser tab is automatically opened. Since this directory is empty, you should now be looking at an empty directory index. +By running `npx @marko/serve`, a browser tab automatically opens for the current working directory. Since our new directory is empty, you should see an empty directory index: - + -![empty directory index](https://user-images.githubusercontent.com/1958812/60997492-c49b7180-a30b-11e9-866f-b984c94c2a25.png) +![A browser viewing the URL of localhost:3000/, which reads “Index of /”.](https://user-images.githubusercontent.com/1958812/60997492-c49b7180-a30b-11e9-866f-b984c94c2a25.png) -Let's get some content in there! Create a `hello.marko` file within `my-new-app` with the following content: +Let's make a web page! Create a `hello.marko` file within `my-new-app/` with the following: ```marko

Hello World

``` -Once you save this file, the directory index will reload and show `hello.marko` as a file in the directory. +Once you save this file, the directory index will reload and show `hello.marko` as a file: -![hello.marko in directory index](https://user-images.githubusercontent.com/1958812/60997582-fc0a1e00-a30b-11e9-8d21-78c57ea8fcbe.png) +![The same URL as before, but now the “Index of /” shows a hyperlink to “hello.marko”.](https://user-images.githubusercontent.com/1958812/60997582-fc0a1e00-a30b-11e9-8d21-78c57ea8fcbe.png) -Click on it to view the new page. Nice! +Follow the `hello.marko` hyperlink to view your new page: -![hello page](https://user-images.githubusercontent.com/1958812/60997682-3a9fd880-a30c-11e9-8a9b-7ba5353fb76a.png) +![The URL of localhost:3000/hello shows a large heading of “Hello World”.](https://user-images.githubusercontent.com/1958812/60997682-3a9fd880-a30c-11e9-8a9b-7ba5353fb76a.png) -## A custom index +### A custom index -Navigate back to the directory index. Let's create an `index.marko` file with the following content: +Navigate back to the directory index. Let's create an `index.marko` file with the following: ```marko

Home

``` -Once you save this file, the directory index will reload and show our custom index instead. +Once you save this file, the directory index will reload and show our custom index instead: -![home page](https://user-images.githubusercontent.com/1958812/60998579-10e7b100-a30e-11e9-853a-af2cd3773d9a.png) +![The URL of localhost:3000/ no longer shows the the “Index of /” page, but instead a heading of “Home”.](https://user-images.githubusercontent.com/1958812/60998579-10e7b100-a30e-11e9-853a-af2cd3773d9a.png) -## Adding a component +### Adding a component -Let's add a menu so we can easily navigate between our two pages. Since we'll be adding this to each page, we'll create it as a component instead of duplicating code on each page. Create a `components/` directory and add a `main-menu.marko` file inside with the following content: +Let's add a menu so we can navigate between our pages. Since it’ll be on every page, we'll create it as a component instead of duplicating code for each page. + +1. Create a `components/` directory, then add a `main-menu.marko` file inside with the following: ```marko ``` -And then we'll add the `` component to both of our pages: +2. Then, add the `` component to both pages: -```marko -

Home

- -``` + ```marko +

Home

+ + ``` -```marko -

Hello World

- -``` + ```marko +

Hello World

+ + ``` -We can now use the menu to navigate between pages! +3. We can now use the menu to navigate between pages! -![home with menu](https://user-images.githubusercontent.com/1958812/60999112-332dfe80-a30f-11e9-9ef6-4f5254a7e19a.png) + ![The Home page at localhost:3000/ now shows hyperlinks to itself and to “Hello”.](https://user-images.githubusercontent.com/1958812/60999112-332dfe80-a30f-11e9-9ef6-4f5254a7e19a.png) -## Route params +### Route params -What if we want our app to be able to say "Hello" to more than just the world? Do we need to create a new page for each thing we want to say hello to? +What if we want our app to say "Hello" to more than the world? Do we need a new `.marko` file for each thing we want to say hello to? -**Nope**. This is where route parameters come in. Route parameters allow you to use dynamic values from the url in your template. Just like normal pages, these are powered by your directory structure, but use a special syntax: files or directories that contain `[PARAM]` indicate a parameter. Let's rename `hello.marko` to `hello/[name].marko` and update its contents to the following: +_Nope._ This is where route parameters come in. **Route parameters** let you use dynamic values from the URL in your templates. Like normal pages, these are powered by your directory structure, but add a special syntax: filenames that contain keywords in square brackets (like `[example]`) create a parameter with the same name as the text between the brackets. -```marko -

Hello ${input.params.name}

- -``` +1. Rename `hello.marko` to `hello/[name].marko`, and update its contents to: -Try visiting [http://localhost:3000/hello/params](http://localhost:3000/hello/params) in your browser. + ```marko +

Hello ${input.params.name}

+ + ``` -![hello params page](https://user-images.githubusercontent.com/1958812/61000022-62de0600-a311-11e9-98e8-c20dee1ad434.png) +2. Try [visiting `http://localhost:3000/hello/params`](http://localhost:3000/hello/params) in your browser. -The possibilities are endless! Let's add a few to our menu: + ![The page at localhost:3000/hello/params shows a heading of “Hello params”.](https://user-images.githubusercontent.com/1958812/61000022-62de0600-a311-11e9-98e8-c20dee1ad434.png) -```marko - -``` +3. The possibilities are endless! Try adding a few to your menu: -## Go forth and build + ```marko + + ``` -When you're ready to let the world see what you've built, run the [`build`](../build/README.md) command to get a production-ready app. +### Go forth and build -``` +When you're ready to let the world see what you've built, run [the `build` command](../build/README.md) to get a production-ready app: + +```sh npx @marko/build . ``` -This produces a `build/` directory that contains the app and its assets, all optimized and compressed. We no longer need `serve`, `build` or any other dependencies. We can run the server using just `node`: +This produces a `build/` directory that contains the app and its assets, all optimized and compressed. -``` +We no longer need `@marko/serve`, `@marko/build`, or any other dependencies. We can run the server using only `node`: + +```sh node build/index.js ``` -Open your browser to [http://localhost:3000/](http://localhost:3000/) and you'll see the same app, only faster. +[Open your browser to `http://localhost:3000/`](http://localhost:3000/) and you'll see the same app, only faster. -![image](https://user-images.githubusercontent.com/1958812/61000788-0da2f400-a313-11e9-892e-b95f5a0d2e0e.png) +![The homepage with a menu of links to “Home”, “Marko”, “Params”, and “World”.](https://user-images.githubusercontent.com/1958812/61000788-0da2f400-a313-11e9-892e-b95f5a0d2e0e.png) -This build directory can now be deployed to your favorite hosting service. We're exicited to see what you come up with! ✨ +This `build/` directory can now be deployed to your favorite hosting service. We're excited to see what you make! ✨ -# CLI +## CLI -## Installation +### Installation -```bash -npm install @marko/serve +```sh +npm install --save-dev @marko/serve ``` -## Example +### Examples -```bash -marko-serve . # serve the current directory -marko-serve ./pages # serve a pages directory -marko-serve ./components/my-component.marko # serve a single component -marko-serve . --inspect-brk # debug by passing node arguments through +```sh +marko-serve . # serve the current directory +marko-serve ./pages # serve a “pages” directory +marko-serve ./components/example.marko # serve a single component +marko-serve . --inspect-brk # debug by passing a node argument through ``` -## Options +### Options -- `--port -p`: The port to serve on +- `--port -p`: The port to serve on (default `3000`) - `--no-browser`: Don't automatically open the browser -- `--verbose`: Show the raw build output -- [node arguments](https://nodejs.org/api/cli.html) are passed to the server process +- `--verbose`: Show the entire raw build output +- [Any `node` CLI arguments](https://nodejs.org/api/cli.html) are passed to the Node.js server process -# API +## API -Do not use the `@marko/serve` package directly. A programatic API is coming soon. +> **Warning**: +> Don't import the `@marko/serve` package directly yet. A programmatic API is coming soon.