Skip to content

Latest commit

 

History

History
284 lines (206 loc) · 7.97 KB

README.md

File metadata and controls

284 lines (206 loc) · 7.97 KB
Raw

Astro Doc

Astro Doc lets you create document layouts with minimal markup in Astro.

NPM Version NPM Downloads Open in StackBlitz

You write this:

---
import Document from '@astropub/doc'
---
<Document title="Astro Doc" body-class="p-body">
  <h1>
    Astro Doc
  </h1>
  <p>
    The HTML, HEAD, and BODY tags are all set.
  </p>
</Document>

You get this:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Astro Doc</title>
    <meta name="viewport" content="width=device-width" />
    <meta name="disabled-adaptations" content="watch" />
    <meta property="og:title" content="Astro Doc" />
  </head>
  <body class="p-body">
    <h1>
      Astro Doc
    </h1>
    <p>
      The HTML, HEAD, and BODY tags are all set.
    </p>
  </body>
</html>

Open in StackBlitz

Usage

Install Astro Doc to your project.

npm install @astropub/doc

Use Astro Doc components in your project.

---
import Document from '@astropub/doc'
---
<Document>
  <p>
    The HTML, HEAD, and BODY tags are all set.
  </p>
</Document>

You get this:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <meta name="disabled-adaptations" content="watch" />
  </head>
  <body>
    <p>
      The HTML, HEAD, and BODY tags are all set.
    </p>
  </body>
</html>

Features

Embedded Attributes

title

Defines the title of the document, without any additional taglines.

<meta property="og:title" content={title} />

description

Defines the summary of the content of the current document.

<meta name="description" content={description} />

sitetitle

Defines the title of the site, without any additional taglines.

<meta property="og:site_name" content={sitetitle} />

tabtitle

Defines the title of the document used by the tab, which may include additional taglines.

<title>{title}</title>

type

Defines the category or type of the current document. By default, this is webpage.

<meta property="og:type" content={type} />

url

Defines the canonical URL of the current document. By default, this is the value of Astro.url. If the URL does not include a protocol or domain, it will be resolved against Astro.site.

<meta property="og:url" content={resolvedURL(url)} />

imageurl

Defines the URL of the image representing the current document. If the URL does not include a protocol or domain, it will be resolved against Astro.site.

<meta property="og:image" content={resolvedURL(imageurl)} />

imagealt

Defines the description for the image representing the current document.

<meta property="og:image:alt" content={imagealt} />

twittercard

Defines the summary card used by Twitter. By default, this is summary_large_image if imageurl is defined.

<meta name="twitter:card" content={twittercard} />

Note: This is the only embedded attribute not shared across social networks.

robots

How search engines should follow the current document.

<meta name="robots" content={robots} />

Application Attributes

viewport

Defines the area through which the document is viewed.

<meta name="viewport" content={viewport} />

disabledadaptations

Defines whether the website is compatible without adaptations smaller viewports.

<meta name="disabled-adaptations" content={disabledadaptations} />

icon

Defines the image used by the website to represent the current document in some browser tabs, browser history views, toolbar apps, bookmarks dropdowns, search bars, and search bar recommendations. The type will be automatically detected.

<link rel="icon" href={icon} type={resolvedIconType(icon)} />

touchicon

Defines the image used by common handheld devices, such as Apple or Android phones. Presently, the size is hard-coded to 180x180.

<link rel="apple-touch-icon" sizes="180x180" href={touchicon} />

charset

Defines the character encoding for the document. By default, this is utf-8.

<meta charset={charset} />

Head Slot

Additional elements may be placed in the <head> tag thru use of the head slot.

---
import Document from '@astropub/doc'
---
<Document title="Astro Doc" body-class="p-body">
  <meta slot="head" name="twitter:creator" content="@jon_neal" />
  <link slot="head" rel="alternate" type="application/rss+xml" title="Blog" href="/blog.xml" />

  <h1>
    Astro Doc
  </h1>
  <p>
    The HTML, HEAD, and BODY tags are all set.
  </p>
</Document>

Project Structure

Inside of this Astro project, you'll see the following folders and files:

/
├── demo/
│   ├── public/
│   └── src/
│       └── pages/
            ├── index.astro
│           └── ...etc
└── packages/
    └── astro-doc/
        ├── package.json
        └── ...etc

This project uses workspaces to develop a single package, @astropub/doc.

It also includes a minimal Astro project, demo, for developing and demonstrating the component.

Commands

All commands are run from the root of the project, from a terminal:

Command Action
npm install Installs dependencies
npm run start Starts local dev server at localhost:3000
npm run build Build your production site to ./dist/
npm run serve Preview your build locally, before deploying

Want to learn more? Read the Astro documentation or jump into the Astro Discord.