📖 Initial work on article-theme docs (#729)

Co-authored-by: Franklin Koch <[email protected]>

docs/_toc.yml

@@ -39,6 +39,7 @@ parts:
       # - file: search
       - file: analytics
       - file: deployment
+      - file: website-themes
       # - file: publishing
   - caption: Documents
     chapters:

docs/frontmatter.md

@@ -152,6 +152,8 @@ Frontmatter can be attached to a “page”, meaning a local `.md` or `.ipynb` o
 
 +++
 
+(thumbnail-and-banner)=
+
 ## Thumbnail & Banner
 
 The thumbnail is used in previews for your site in applications like Twitter, Slack, or any other link preview service. This should, by convention, be included in a `thumbnails` folder next to your content. You can also explicitly set this field to any other image on your local file system or a remote URL to an image. This image will get copied over to your public folder and optimized when you build your project.

docs/website-themes.md

@@ -0,0 +1,41 @@
+---
+title: Website Themes
+description: Export to over 400 journal templates from a MyST Markdown file, which uses LaTeX and can create print-ready, multi-column, professional PDF documents.
+---
+
+There are currently two themes for MyST websites, a book-theme, which is the default and is based loosely on JupyterBook and an article-theme that is designed for scientific documents with supporting notebooks. The documentation for this site is using the `book-theme`, for a demonstration of the `article-theme`, you can see [an article on finite volume](https://simpeg.xyz/tle-finitevolume).
+
+:::::{tab-set}
+::::{tab} Article Theme
+:::{figure} ./images/article-theme.png
+Example of a banner in a site using the `article-theme`, ([online](https://simpeg.xyz/tle-finitevolume/), [source](https://github.com/simpeg/tle-finitevolume))
+:::
+::::
+
+::::{tab} Book Theme
+:::{figure} ./images/book-theme.png
+Example of a site using the `book-theme`, ([online](https://mystmd.org), [source](https://github.com/executablebooks/mystmd/tree/main/docs))
+:::
+::::
+:::::
+
+## Changing Themes
+
+To change your website theme from the default (`book-theme`), use the `site: theme:` property:
+
+```{code} yaml
+:filename: myst.yml
+:emphasize-lines: 4
+:caption: Change the `theme` property to `article-theme`.
+:linenos:
+project:
+  ...
+site:
+  theme: article-theme
+```
+
+### Article Theme
+
+The article theme is centered around a single document with supporting content, which is how many scientific articles are structured today: a narrative article with associated computational notebooks to reproduce a figure, document data-cleaning steps, or provide interactive visualization. These are listed as "supporting documents" in this theme and can be pulled in as normal with your [](./table-of-contents.md). For information on how to import your figures into your article, see [](./reuse-jupyter-outputs.md).
+
+The frontmatter that is displayed at the top of the article is the contents of your project, including a project [thumbnail and banner](#thumbnail-and-banner). The affiliations for your authors, their ORCID, email, etc. are available by clicking directly on the author name.