diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 7df675ed..00000000 --- a/docs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Wowchemy Documentation - -This is the public repository for [Wowchemy Documentation](http://wowchemy.com/docs/), a static website generated with the [Documentation template](https://wowchemy.com/hugo-themes/). - -We intend the docs to be read on the website. You can also read them here but be warned that links won't often work and other things may appear missing or less than optimal. - -## Edit the docs - -If you have an improvement, please click the pencil button to edit the file on GitHub and then click the _Commit_ (save) button to easily submit it as a PR for review. - -Otherwise, if you cannot find the file to edit in this repo, please open an issue with the improved text or suggestion. - -## License - -Documentation (including guides, references, and associated images) are licensed under a [Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License](http://creativecommons.org/licenses/by-nc-nd/4.0/). - -Code snippets are licensed under the MIT license. diff --git a/docs/config.yaml b/docs/config.yaml deleted file mode 100644 index 534551b1..00000000 --- a/docs/config.yaml +++ /dev/null @@ -1,7 +0,0 @@ -module: - mounts: - - source: media/docs - target: assets/media/docs - - source: en - target: content/docs - lang: en diff --git a/docs/en/content/page-features.md b/docs/en/content/page-features.md deleted file mode 100644 index db29ddde..00000000 --- a/docs/en/content/page-features.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: 🏷 Page Features -date: 2016-04-18 -lastmod: 2022-09-03 -weight: 20 -summary: Learn how to add featured images, attach files, and use metadata to control page features such as author profile cards, comments, and math. ---- - -Wowchemy empowers you create a wide variety of different content types. Content can include widget pages, blog posts, publications, online courses, podcasts, videos, Markdown slides, notebooks, documentation, projects, events/talks, and much more. - -{{< toc hide_on="xl" >}} - -You may also be interested to learn about the diverse range of [**page elements**]({{< relref "writing-markdown-latex.md" >}}), such as image galleries, math, or diagrams, that can be added to any page. - -## Introduction - -The following common metadata can be added to the [front matter]({{< relref "front-matter.md" >}}) of most types of page in Wowchemy. - -**Core metadata:** - -- **title**: the title of your page -- **summary**: a one-sentence summary of the content on your page. The summary can be shown on the homepage and can also benefit your search engine ranking. -- **date**: the [RFC 3339 date](https://github.com/toml-lang/toml#local-date-time) that the page was published. A future date will schedule the page to be published in the future. If you use the `hugo new ...` commands described on this page, the date will be filled automatically when you create a page. Also see **lastmod** and **publishDate**. -- **authors**: display the authors of the page and link to their user profiles if they exist. To link to a user profile, [create a user]({{< relref "get-started.md#introduce-yourself" >}}) based on the [*admin* template](https://github.com/wowchemy/starter-academic/tree/master/exampleSite/content/authors) and reference their username (the name of a user in your `authors` folder) in the `authors` field, e.g. `authors: ["admin"]`. To format a name in bold, see the relevant section below. -- **author_notes**: display author contributions, affiliations, and other details as a tooltip next to the author's name (see section below) -- **tags**: tagging your content helps users to discover similar content on your site. Tags can improve search relevancy and are displayed after the page content and also in the [Tag Cloud widget]({{< relref "page-builder.md" >}}). E.g. `tags: ["Electronics", "Diodes"]`. - -**Popular metadata:** - -- **subtitle**: an optional subtitle that will be displayed under the title -- **featured**: by setting `featured: true`, a page can be displayed in the [Featured widget]({{< relref "page-builder.md" >}}). This is useful for *sticky, announcement blog posts* or *selected publications* etc. -- **categories**: categorizing your content helps users to discover similar content on your site. Categories can improve search relevancy and display at the top of a page alongside a page's metadata. E.g. `categories: ["Art"]`. -- **lastmod**: the [RFC 3339 date](https://github.com/toml-lang/toml#local-date-time) that the page was last modified. - - By default, there's no need to specify `lastmod` as the **page modification date is automatically updated** from Git according to the `HUGO_ENABLEGITINFO` option in `netlify.toml` (or the equivalent `enableGitInfo` option in `config.yaml`) - - **To hide the automatic last modified date**, change `HUGO_ENABLEGITINFO` to `"false"` in `netlify.toml` -- **publishDate**: the [RFC 3339 date](https://github.com/toml-lang/toml#local-date-time) that the page was published. You only need to specify this option if you wish to set **date** in the future but publish the page *now*, as is the case for publishing a journal article that is to appear in a journal etc. -- **draft**: by setting `draft: true`, only you will see your page when you preview your site locally on your computer -- **private**: hide page in search results -- **feedback**: by setting `feedback: false`, you can remove the feedback widget from the Book layout - -A complete list of standard options can be found on the corresponding [Hugo docs page](https://gohugo.io/content-management/front-matter/#predefined). - -## Cover image - -To display a **cover image** (aka _featured_ image) in content pages, simply drag an image named `featured.*` (e.g. `featured.jpg`) into your page's folder. - -{{% callout note %}} -If your page does not have its own folder ([*page bundle*](https://gohugo.io/content-management/page-bundles/)) within its section folder, you can refactor a page named `NAME.md` to `NAME/index.md`, creating the folder `NAME`. There is a [tool to help automate this process](https://github.com/wowchemy/awesome-hugo). -{{% /callout %}} - -Want to caption the image or set a focal point to influence how the image is cropped? - -The parameters below can be added to the bottom of your page front matter to customize the appearance of the image. The caption supports Markdown and can be used to write an image caption or credit. The focal point ensures that the image subject is in view when the image is resized. - -```yaml -# Cover image -# To use, place an image named `featured.jpg/png` in your page's folder. -# Otherwise, specify the `filename` option to load an image from your `assets/media/` folder. -# Placement options: 1 = Full column width, 2 = Out-set, 3 = Screen-width -# Focal point options: Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight -# Set `preview_only` to `true` to just use the image for thumbnails. -image: - placement: 1 - caption: "Photo by [Geo](https://github.com/gcushen/)" - focal_point: "Center" - preview_only: false - alt_text: An optional description of the image for screen readers. - # filename: my-image.jpg # Uncomment to load an image from `assets/media/` instead. -``` - -For the Book layout (i.e. docs pages), just the filename, caption, and alt_text options apply. - -## Page resources (attachments and links) - -Buttons can be generated in the page header to link to associated resources. - -The example below shows how to create a Twitter link for a project and how to create a link to a post that was originally published on Medium: - -```yaml -links: - - icon_pack: fab - icon: twitter - name: Follow - url: 'https://twitter.com/Twitter' - - icon_pack: fab - icon: medium - name: Originally published on Medium - url: 'https://medium.com' - -``` - -The only required option is `url`, giving you the option to show a *text button*, an *icon button*, or a *combination of both*. [Learn more about icons]({{< relref "page-builder.md#icons" >}}). - -To generate a **PDF button**, add a PDF file with the same name as your page's own folder to your page's folder and a PDF link will be automatically generated. For example, if your page is located at `publication/photons/index.md`, place a PDF at `publication/photons/photons.pdf`. This can be useful for talks and publications. - -There are also several special built-in buttons that can be setup using `url_...` options in the front matter of some content types. - -## Page features - -The following parameters can be added to the front matter of a page (such as a blog post) to control its features: - -```yaml -# Show the page's date? -show_date: true - -# Show estimated reading time? -reading_time: true - -# Show social sharing links? -share: true - -# Show author profile (photo and bio) under the content? -# Edit your author profiles in the `content/authors/` folder -# Then reference their folder names with the `authors` front matter option above -profile: true - -# Allow users to comment on the page? -# Requires commenting to be configured in `params.yaml` -commentable: true - -# Allow visitors to make improvements to the page? -# Requires a repository to be configured in `params.yaml` -editable: true - -# Show a link to the next article in the series? -pager: true - -# Show recommendations for related content? -show_related: true - -# Show breadcrumb navigation? -show_breadcrumb: true - -# Hide the navigation bar? -# Often used together with `show_breadcrumb` -header: - navbar: - enable: false -``` - -### Highlight authors in author lists - -Specific author names can be highlighted in bold in author lists, for example if you wish to highlight yourself or your colleagues. - -If you wish to highlight an author name in bold, add `highlight_name: true` to their author profile. The default user profile can be found at `content/authors/admin/_index.md` ([view example](https://raw.githubusercontent.com/wowchemy/starter-academic/main/content/authors/admin/_index.md)). - -### Add author notes for affiliations and contributions - -**Author notes** can be added to a page's front matter in the form: - - authors: - - "Someone" - - "Someone else" - - "Dr No" - author_notes: - - "Equal contribution" - - "Equal contribution" - - "Stanford University" - -where the index of each author note corresponds with an author in the `authors` list. - -An author note is rendered as a tooltip next to an author's name: - -{{< figure src="docs/author-notes.png" title="Add author notes for affiliations and contributions." >}} - -### How to configure a page collection? - -Control page features for an **entire collection of pages** by using [Hugo cascades](https://gohugo.io/getting-started/configuration/#cascade) in `config.yaml`. - -For example, to configure blog posts in `config.yaml`: - -```yaml -cascade: - # Configure blog posts - - _target: - path: /post/** - pager: true - editable: true - reading_time: true - commentable: true - show_related: true - show_breadcrumb: true - share: true - header: - navbar: - enable: false -``` - -### LaTeX math - -If your site uses LaTeX math (equations), you can choose between enabling math for all pages (recommended) or just on specific pages. - -To enable **LaTeX math** rendering for a specific page, include `math: true` in the page's front matter. - -Otherwise, to enable math for all pages, set the math option in the site configuration at `config/_default/params.yaml`: - -```yaml -features: - math: - enable: true -``` - -Also, refer to the [math guide]({{< relref "writing-markdown-latex.md" >}}) for further details. - -## Banner image - -To display a full width **banner image**, the parameters below can be inserted towards the end of a page's [front matter]({{< relref "front-matter.md" >}}). It is assumed that the image is located in your `assets/media/` media library, so the full path in the example below will be `assets/media/header.png`. The `caption` parameter supports Markdown and can be used to write an image caption or credit. This option can be particularly useful for adding to an archive page's `_index.md` (e.g. to display at `YOUR_URL/post/` for the blog post archive). - -```yaml -banner: - image: "header.png" - caption: "Image credit: [**Geo**](https://github.com/gcushen/)" -``` - -## Unpublish pages - -To temporarily unpublish content, set `draft: true` at the top of a page's front matter. - -To remove content permanently, simply delete the relevant page file/folder within your `content/` folder. - -## Private pages - -Want to try to share a page with only a few specific people? - -Add the following to the page front matter before publishing it, to prevent it appearing in any page collections: - -```yaml -_build: - render: always - list: never -``` - -## Password protect pages - -By nature, static pages are viewable by anyone who visits their URLs. - -Some content delivery networks, such as [Netlify](https://docs.netlify.com/visitor-access/password-protection/), offer a service allowing you to restrict access. diff --git a/docs/en/content/writing-markdown-latex/index.md b/docs/en/content/writing-markdown-latex/index.md deleted file mode 100644 index 1f3f2c5b..00000000 --- a/docs/en/content/writing-markdown-latex/index.md +++ /dev/null @@ -1,682 +0,0 @@ ---- -title: "📸 Page Elements: Writing content with Markdown, LaTeX, and Shortcodes" -linktitle: 📸 Page Elements -date: 2016-04-17 -lastmod: 2022-08-21 -weight: 30 -math: true -summary: Learn how to format content with Markdown, write math with LaTeX, add citations, and embed rich media such as image galleries, videos, podcasts, and Twitter feeds. ---- - -Rich content can be written in Wowchemy using **Markdown**, [**LaTeX math**](https://en.wikibooks.org/wiki/LaTeX/Mathematics), and **Shortcodes**. This article gives an overview of the most common formatting options, including features that are exclusive to Wowchemy. - -{{% callout note %}} -*Shortcodes* are plugins which are bundled with Wowchemy or inherited from [Hugo](http://gohugo.io/extras/shortcodes/). Additionally, **HTML** may be written in Markdown documents for advanced formatting. -{{% /callout %}} - -{{< toc hide_on="xl" >}} - -## Sub-headings - -After the page title, heading 1, we can format sub-headings in the page body: - -```markdown -## Heading 2 -### Heading 3 -#### Heading 4 -``` - -## Emphasis - -### Bold, Italic, Strikethrough - -```markdown -Italics with _underscores_. - -Bold with **asterisks**. - -Combined emphasis with **asterisks and _underscores_**. - -Strikethrough with ~~two tildes~~. -``` - -Italics with _underscores_. - -Bold with **asterisks**. - -Combined emphasis with **asterisks and _underscores_**. - -Strikethrough with ~~two tildes~~. - -### Text color - -Add the [HTML color](https://www.google.com/search?q=color+picker) attribute in the form `{style="color: red"}` to the line _after_ a Markdown block. - -For example, to color a paragraph red: - -```Markdown -Red colored text -{style="color: red"} -``` - -### Blockquote - - > This is a blockquote. - -> This is a blockquote. - -### Highlight quote - - This is a {{}}highlighted quote{{}}. - -This is a {{< hl >}}highlighted quote{{< /hl >}}. - -## Lists -### Ordered - - 1. First item - 1. A sub-item - 2. Another item - -1. First item - 1. A sub-item -2. Another item - -### Unordered - - - First item - - A sub-item - - Another item - -- First item - - A sub-item -- Another item - -### Todo - -Todo lists can be written in Wowchemy by using the standard Markdown syntax: - -```markdown -- [x] Write math example - - [x] Write diagram example -- [ ] Do something else -``` - -renders as - -- [x] Write math example - - [x] Write diagram example -- [ ] Do something else - -### Toggle lists - -Add a toggle list to a page to reveal text, such as an answer to a question, after a toggle button is clicked. - -Useful for FAQs, spoilers, or hiding answers when teaching online courses. - -```markdown -{{}} -You found me! -{{}} -``` - -renders as - -{{< spoiler text="Click to view the spoiler" >}} You found me! {{< /spoiler >}} - -## Links - -### Link to a page - - [I'm an external link](https://www.google.com) - [A post]({{}}) - [A publication]({{}}) - [A project]({{}}) - [A relative link from one post to another post]({{}}) - [Scroll down to a page section with heading *Hi*](#hi) - -You can also [create a button link in the **page header**]({{< relref "_index.md#page-resources" >}}) of any page except Widget Pages (the homepage). - -### Link to a file - -You can [create a button link to a file in the **page header**]({{< relref "_index.md#page-resources" >}}) of any page except Widget Pages (the homepage). - -Otherwise, to link to a file, such as a PDF, in the **body** of your content, place the file in your `static/uploads/` folder and then link to it using the following form: - - {{%/* staticref "uploads/cv.pdf" "newtab" */%}}Download my CV{{%/* /staticref */%}} - -The optional `"newtab"` argument for `staticref` will cause the link to be opened in a new tab. - -### Cite - -To cite a page or publication, you can use the _cite_ shortcode, referencing a folder and page name that you created: - - {{}} - -where _view_ corresponds to one of the available listing views used throughout Wowchemy: - -1. Stream -2. Compact -3. Card -4. Citation - a traditional academic citation, configured by the `citation_style` setting in `params.yaml` - -If you don't specify a view, it will default to the _compact_ view. - -### Table of Contents - -A table of contents can help users navigate long pages. - -Paste the `{{}}` shortcode wherever you would like a table of contents to appear in your page. - -You may also wish to consider using the [_book_ layout]({{< relref "docs.md" >}}) which displays a built-in table of contents in a right sidebar on large screens. - -When using the _book_ layout, you may still wish to add an in-page table of contents which only appears when the right sidebar is hidden. You can do this with `{{}}`. - -### Footnotes - - I have more [^1] to say. - - [^1]: Footnote example. - -I have more [^1] to say. -[^1]: Footnote example. - -### Figures - -To cross-reference a figure, provide it with an ID, for example: `{{}}`. - -The figure can now be cross-referenced with a link in the form `[A Figure](#figure-wowchemy)`. - -### Tags and Categories - -Use `{{}}` to provide a list of linked tags or `{{}}` to provide a list of linked categories. - -### Call-to-Action Buttons - -**Create buttons and call-to-actions (CTA)** with the _CTA_ shortcode. - -Example CTA button: - -``` -{{}} -``` - -Example CTA button with a link to an alternate action: - -``` -{{}} -``` - -### Mention a user - -To mention someone, type `{{%/* mention "username" */%}}` where `username` corresponds to a user account in Wowchemy. - -### List child pages - -To list child pages, such as to list book sections from a book chapter, use `{{}}`. - -## Images - -### Single image - -Images may be added to a page by either placing them in your `assets/media/` media library or in your [page's folder](https://gohugo.io/content-management/page-bundles/), and then referencing them using one of the following notations. - -Figures are **themeable** according to light/dark mode and can also be [**cross-referenced**](#links). - -A figure from your page's folder or your `assets/media/` media library: - - ![screen reader text](image.jpg "caption") - -For more customizable figures, we can use the built-in Figure shortcode rather than the Markdown figure syntax above. - -A numbered figure with a caption: - - {{}} - -**Using light/dark mode?** Did you know that you can create **dynamically themed light/dark images?** - -{{< figure src="/uploads/docs/image-theming.gif" title="Dynamically theme images according to the user's light/dark preference" >}} - -To **dynamically theme images** according to the user's light or dark theme - - - `{{}}` inverts image when browsing in dark mode - - `{{}}` inverts image when browsing in light mode - -Alternatively, paste a **themeable inline SVG image** in the form `...` directly into your Markdown. - -### Image gallery - -**To add an image gallery to a page:** - -1. Create a photo album folder in `assets/media/albums/` - - Album names must be **lowercase** due to a [Hugo bug](https://github.com/gohugoio/hugo/issues/7686) - consider up-voting the bug with a 👍 -2. Add images to your album folder -3. Paste `{{" */>}}` where you would like the gallery to appear in the page content, changing the album parameter to match the name of your album folder - -**How can I change the size or shape of gallery images?** - -Simply add `resize_options` when you call the gallery shortcode. This option lets you control the shape/size of gallery images using the standard [Hugo resize options](https://gohugo.io/content-management/image-processing/#resize). For example: - -```go -{{" resize_options="250x250" */>}} -``` - -**How can I add captions to gallery images?** - -Optionally, to add captions for your images, add the following instances to the end of your page's front matter: - -```yaml -gallery_item: -- album: - image: .jpg - caption: Write your image 1 caption here -- album: - image: .jpg - caption: Write your image 2 caption here -``` - -### Inline image - -Wowchemy enables you to use a wide range of [inline images (aka icons) from _Font Awesome_ and _Academicons_]({{< relref "page-builder.md#icons" >}}) in addition to [emojis](#emojis). There is also an [issue](https://github.com/wowchemy/wowchemy-hugo-themes/issues/1698) open to add support for custom images. - -Here are some examples using the _icon_ shortcode to render icons: - -```markdown -{{}} Terminal -{{}} Python -{{}} R -``` - -renders as - -{{< icon name="terminal" pack="fas" >}} Terminal -{{< icon name="python" pack="fab" >}} Python -{{< icon name="r-project" pack="fab" >}} R - -Optionally, left and right padding can be added to an icon using the `padding_left="3"` and `padding_right="3"` options, respectively. - -### Emojis - -An emoji can be inserted using either an emoji keyboard or by typing the name of the emoji. - -Don't have an emoji keyboard? - -Copy and paste emoji names from the [Emoji cheat sheet](http://www.webpagefx.com/tools/emoji-cheat-sheet/). The following serves as an example, but remember to remove the added spaces between each emoji name and surrounding colons: - - I : heart : Wowchemy : smile : - -I :heart: Wowchemy :smile: - -## Twitter - -### Embed a feed - -[Design your timeline on Twitter](https://help.twitter.com/en/using-twitter/embed-twitter-feed) and paste it into a Markdown page. - -### Embed a single tweet - -To include a single tweet, pass the tweet’s user (case-insensitive) and ID from the URL as parameters to the shortcode: - - {{}} - -## Callouts - -Wowchemy supports a Markdown extension for callouts, also referred to as _alerts_ or _asides_. - -Callouts are a useful feature to **draw attention to important or related content** such as notes, hints, or warnings in your articles. They are especially handy when writing educational tutorial-style articles or documentation. - -A callout can be created by using the _Callout_ shortcode below. - -Wowchemy comes built-in with a few different styles of callouts. - -The paragraph will render as a callout with the default *note* style: - - {{%/* callout note */%}} - A Markdown callout is useful for displaying notices, hints, or definitions to your readers. - {{%/* /callout */%}} - -This will display the following *note* block: - -{{% callout note %}} -A Markdown callout is useful for displaying notices, hints, or definitions to your readers. -{{% /callout %}} - -Alternatively, a warning can be displayed to the reader using the _warning_ option: - - {{%/* callout warning */%}} - Here's some important information... - {{%/* /callout */%}} - -This will display the following *warning* notice to the reader: - -{{% callout warning %}} -Here's some important information... -{{% /callout %}} - -## Audio - -You can add a podcast or music to a page by placing the MP3 file in the page's folder and then referencing the audio file using the _audio_ shortcode: - - {{}} - -## Videos - -The following kinds of video may be added to a page. - -**Local video file** - -Videos may be added to a page by either placing them in your `assets/media/` media library or in your [page's folder](https://gohugo.io/content-management/page-bundles/), and then referencing them using one of the following notations. - -A video from your page folder or your `assets/media/` media library: - - {{}} - -Wowchemy will search for the video in your page folder and your media library at `assets/media/`. - -**External video file** - - {{}} - -If you don't want video controls, remove the `controls` parameter and the video will autoplay with looping (great for memes!). - -Note that browsers will block autoplay if the video contains sound. - -**Youtube**: - - {{}} - -**Vimeo**: - - {{}} - -## Charts - -Wowchemy supports the popular [Plotly](https://plot.ly/) chart format. - -Save your Plotly JSON in your page folder, for example `chart.json`, and then add the `{{}}` shortcode where you would like the chart to appear. - -Demo: - -{{< chart data="line-chart" >}} - -You might also find the [Plotly JSON Editor](http://plotly-json-editor.getforge.io/) useful. - -## Mindmaps - -Wowchemy supports a Markdown extension for mindmaps. - -Simply insert a Markdown `markmap` code block and optionally set the height of the mindmap as shown in the first example below. - -A simple mindmap defined as a Markdown list: - -
-
-
-```markmap {height="200px"}
-- Hugo Modules
-  - wowchemy
-  - wowchemy-plugins-netlify
-  - wowchemy-plugins-netlify-cms
-  - wowchemy-plugins-reveal
-```
-
-
-
- -renders as - -```markmap {height="200px"} -- Hugo Modules - - wowchemy - - wowchemy-plugins-netlify - - wowchemy-plugins-netlify-cms - - wowchemy-plugins-reveal -``` - -A more advanced mindmap with formatting, code blocks, and math: - -
-
-
-```markmap
-- Mindmaps
-  - Links
-    - [Wowchemy Docs](https://wowchemy.com/docs/)
-    - [Discord Community](https://discord.gg/z8wNYzb)
-    - [GitHub](https://github.com/wowchemy/wowchemy-hugo-themes)
-  - Features
-    - Markdown formatting
-    - **inline** ~~text~~ *styles*
-    - multiline
-      text
-    - `inline code`
-    -
-      ```js
-      console.log('hello');
-      console.log('code block');
-      ```
-    - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
-```
-
-
-
- -renders as - -```markmap -- Mindmaps - - Links - - [Wowchemy Docs](https://wowchemy.com/docs/) - - [Discord Community](https://discord.gg/z8wNYzb) - - [GitHub](https://github.com/wowchemy/wowchemy-hugo-themes) - - Features - - Markdown formatting - - **inline** ~~text~~ *styles* - - multiline - text - - `inline code` - - - ```js - console.log('hello'); - console.log('code block'); - ``` - - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ -``` - -## Embed Documents - -The following kinds of document may be embedded into a page. - -To embed **Google Documents** (e.g. slide deck), click *File > Publish to web > Embed* in Google Docs and copy the URL within the displayed `src="..."` attribute. Then paste the URL in the form: - - {{}} - -## Diagrams - -Wowchemy supports the [Mermaid](https://mermaidjs.github.io) Markdown extension for diagrams. Simply draw your diagram within a *mermaid* code block and it will be rendered when your page is published. Check out the Mermaid documentation and the [Mermaid editor](https://mermaid.live/) for more examples in addition to those below: - -An example **flowchart**: - - ```mermaid - graph TD; - A-->B; - A-->C; - B-->D; - C-->D; - ``` - -renders as - -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -``` - -An example **sequence diagram**: - - ```mermaid - sequenceDiagram - participant Alice - participant Bob - Alice->John: Hello John, how are you? - loop Healthcheck - John->John: Fight against hypochondria - end - Note right of John: Rational thoughts
prevail... - John-->Alice: Great! - John->Bob: How about you? - Bob-->John: Jolly good! - ``` - -renders as - -```mermaid -sequenceDiagram - participant Alice - participant Bob - Alice->John: Hello John, how are you? - loop Healthcheck - John->John: Fight against hypochondria - end - Note right of John: Rational thoughts
prevail... - John-->Alice: Great! - John->Bob: How about you? - Bob-->John: Jolly good! -``` - -An example **Gantt diagram**: - - ```mermaid - gantt - dateFormat YYYY-MM-DD - section Section - A task :a1, 2014-01-01, 30d - Another task :after a1 , 20d - section Another - Task in sec :2014-01-12 , 12d - another task : 24d - ``` - -renders as - -```mermaid -gantt - dateFormat YYYY-MM-DD - section Section - A task :a1, 2014-01-01, 30d - Another task :after a1 , 20d - section Another - Task in sec :2014-01-12 , 12d - another task : 24d -``` - -### Advanced diagrams - -More advanced diagrams can be created in the open source [draw.io](https://draw.io) editor. The editor has support for almost any type of diagram, from simple to complex. A diagram can be easily embedded in Wowchemy by choosing **File > Embed > SVG** in the [draw.io](https://draw.io) editor and pasting the generated code into your page. - -Alternatively, a diagram can be exported as an [image](#images) from any drawing software, or a [document/slide](#embed-documents) containing a diagram can be embedded. - -## Code highlighting - -Pass the *language* of the code, such as `python`, as a parameter after three backticks: - - ```python - # Example of code highlighting - input_string_var = input("Enter some data: ") - print("You entered: {}".format(input_string_var)) - ``` -Result: - -```python -# Example of code highlighting -input_string_var = input("Enter some data: ") -print("You entered: {}".format(input_string_var)) -``` - -You can also [customize the highlighter theme]({{< relref "/docs/getting-started/customization.md#code-syntax-highlighting" >}}). - -## Jupyter Notebook - -[**View the guide to blogging with Jupyter Notebooks**]({{< relref "/docs/import/jupyter.md" >}}). - -## GitHub gist - - {{}} - -## Math - -Wowchemy supports a Markdown extension for $\LaTeX$ math. You can enable this feature by toggling the `math` option in your `config/_default/params.yaml` file. - -To render *inline* or *block* math, wrap your LaTeX math with `{{}}$...${{}}` or `{{}}$$...$${{}}`, respectively. (We wrap the LaTeX math in the Wowchemy _math_ shortcode to prevent Hugo rendering our math as Markdown. The _math_ shortcode is new in v5.5.) - -Example **math block**: - -```latex -{{}} -$$ -\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2} -$$ -{{}} -``` - -renders as - -{{< math >}} -$$\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}$$ -{{< /math >}} - -Example **inline math** `{{}}$\nabla F(\mathbf{x}_{n})${{}}` renders as {{< math >}}$\nabla F(\mathbf{x}_{n})${{< /math >}}. - -Example **multi-line math** using the math linebreak (`\\`): - -```latex -{{}} -$$f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\ -1-p_{0}^{*} & \text{if }k=0.\end{cases}$$ -{{}} -``` - -renders as - -{{< math >}} -$$f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\ -1-p_{0}^{*} & \text{if }k=0.\end{cases}$$ -{{< /math >}} - -**Math in front matter** - -Math is primarily intended for use within the page body, but can also be added to page front matter variables such as a publication abstract with some additional checks. - -As Hugo and Wowchemy can attempt to parse YAML, Markdown, and LaTeX content in the front matter, Markdown special characters need to be escaped in any math within the front matter fields by using a backslash to prevent the math being parsed as Markdown. The following tips may help: - -- escape each LaTeX backslash (`\`) with an extra backslash, yielding `\\` -- escape each LaTeX underscore (`_`) with two backslashes, yielding `\\_` - -Hence, `abstract: "${O(d_{\max})}$"` becomes `abstract: "${O(d\\_{\\max})}$"`. - -## Subscripts & superscripts - -Subscripts and superscripts can be written direct from a (unicode) keyboard or [pasted from a reference](https://en.wikipedia.org/wiki/Unicode_subscripts_and_superscripts). - -Alternatively, you can enable `math` in `params.yaml` and use the Latex notation, for example `$^2$`. - -## Tables - -### Markdown Table - -For quick, simple tables, use the [Markdown table generator](https://www.tablesgenerator.com/markdown_tables) and paste the resulting Markdown into your page. - -### CSV Table - -For larger tables, save your spreadsheet as a CSV file in your page's folder and then render it by adding the _Table_ shortcode to your page: - -```go -{{}} -``` - -### Google Sheets - -See the [Embed Documents](#embed-documents) section. diff --git a/docs/en/content/writing-markdown-latex/line-chart.json b/docs/en/content/writing-markdown-latex/line-chart.json deleted file mode 100644 index 446ce82a..00000000 --- a/docs/en/content/writing-markdown-latex/line-chart.json +++ /dev/null @@ -1,77 +0,0 @@ -{ - "data": [ - { - "uid": "babced", - "fill": "tonexty", - "mode": "none", - "name": "Col2", - "type": "scatter", - "x": [ - "2000-01-01", - "2001-01-01", - "2002-01-01", - "2003-01-01", - "2004-01-01", - "2005-01-01", - "2006-01-01", - "2007-01-01", - "2008-01-01", - "2009-01-01", - "2010-01-01", - "2011-01-01", - "2012-01-01", - "2013-01-01", - "2014-01-01", - "2015-01-01", - "2016-01-01" - ], - "y": [ - "17087182", - "29354370", - "38760373", - "40912332", - "51611646", - "64780617", - "85507314", - "121892559", - "172338726", - "238027855", - "206956723", - "346004403", - "697089489", - "672985183", - "968882453", - "863105652", - "1068513050" - ], - "fillcolor": "rgb(224, 102, 102)" - } - ], - "layout": { - "title": "Total Number of Websites", - "width": 800, - "xaxis": { - "type": "date", - "range": [ - 946702800000, - 1451624400000 - ], - "title": "Source: Scribblrs
Source: Internet Live Stats", - "showgrid": false, - "autorange": true, - "tickformat": "%Y" - }, - "yaxis": { - "type": "linear", - "range": [ - 0, - 1124750578.9473684 - ], - "title": "", - "autorange": true - }, - "height": 500, - "autosize": false - }, - "frames": [] -} diff --git a/docs/en/import/_index.md b/docs/en/import/_index.md deleted file mode 100644 index b52ba20c..00000000 --- a/docs/en/import/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Import -icon_pack: fas -icon: file-import -weight: 200 -cms_exclude: true ---- diff --git a/docs/en/import/jupyter.md b/docs/en/import/jupyter.md deleted file mode 100644 index aa2b917b..00000000 --- a/docs/en/import/jupyter.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Import Jupyter Notebooks -linktitle: From Jupyter Notebooks -date: 2019-02-12 -summary: Learn how to write and import Jupyter Notebooks from JupyterLab. ---- - -In this guide, we'll **learn how to blog in Wowchemy using Jupyter Notebooks**. - -Here's a snippet from a Jupyter notebook, for example: - -```python -print("I am a Jupyter Notebook!") -``` - - I am a Jupyter Notebook! - -## Install Python and Jupyter - -[Install Anaconda](https://www.anaconda.com/distribution/#download-section) which includes Python 3 and Jupyter notebook. - -Otherwise, for advanced users, install Jupyter notebook with `pip3 install jupyter`. - -## Create a new blog post [as usual]({{< relref "../content/_index.md#create-a-blog-post" >}}) - -Run the following commands in your Terminal, substituting `` and `my-post` with the file path to your Wowchemy website folder and a name for your blog post (without spaces), respectively: - -```bash -cd -hugo new --kind post post/my-post -cd /content/post/my-post/ -``` - -## Create or upload a Jupyter notebook - -Run the following command to start Jupyter within your new blog post folder. Then create a new Jupyter notebook (*New > Python Notebook*) or upload a notebook. - -```bash -jupyter notebook -``` - -## Convert notebook to Markdown - -```bash -jupyter nbconvert Untitled.ipynb --to markdown --NbConvertApp.output_files_dir=. - -# Copy the contents of Untitled.md and append it to index.md: -cat Untitled.md | tee -a index.md - -# Remove the temporary file: -rm Untitled.md -``` - -## Edit your post metadata - -Open `index.md` in your text editor and edit the title etc. in the [front matter]({{< relref "front-matter.md" >}}) according to your preference. - -To set a [featured image]({{< relref "../content/_index.md#featured-image" >}}), place an image named `featured` into your post's folder. - -For other tips, such as using math, see the guide on [writing content with Wowchemy]({{< relref "../content/writing-markdown-latex.md" >}}). - -## Alternative approaches - -Alternatively, a Jupyter notebook can be embedded in a page by following one of the approaches below: - -1. Upload your notebook as a [GitHub Gist](https://gist.github.com) and click *Embed* to copy and paste your hosted notebook into the body of content in Wowchemy - -2. [Convert your notebook to HTML]( -https://nbconvert.readthedocs.io/) using `jupyter nbconvert --to html .ipynb`. Then move the resulting HTML file to your page's folder and embed it into the body of the page's Markdown file using: - - - -3. Upload your notebook to a cloud notebook service such as [Microsoft Azure](https://notebooks.azure.com/), [Google Cloud Datalab](https://cloud.google.com/datalab/) or [Kyso](https://kyso.io). Then click their *Embed* button, pasting their custom embedding code into the body of your page's Markdown file - -4. Copy snippets of code from your notebook and paste them into the body of your page using [Wowchemy's code highlighting]({{< relref "../content/writing-markdown-latex.md#code-highlighting" >}}) diff --git a/docs/en/import/migrate-from-jekyll.md b/docs/en/import/migrate-from-jekyll.md deleted file mode 100644 index a742627c..00000000 --- a/docs/en/import/migrate-from-jekyll.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Migrate from Jekyll -linktitle: From Jekyll -date: 2014-03-10 -summary: Learn how to migrate your site from Jekyll to the Wowchemy website building framework for Hugo. ---- - -Here are a few tips for migrating an existing website from Jekyll to Hugo. These tips can be applied in conjunction with following Hugo Wowchemy's [getting started guide]({{< relref "get-started.md" >}}). - -## Move static content to `static` -Jekyll has a rule that any directory not starting with `_` will be copied as-is to the `_site` output. Hugo keeps all static content under `static`. You should therefore move it all there. -With Jekyll, something that looked like - - ▾ / - ▾ images/ - logo.png - -should become - - ▾ / - ▾ static/ - ▾ images/ - logo.png - -Additionally, you'll want any files that should reside at the root (such as `CNAME`) to be moved to `static`. - -## Fix content -Depending on the amount of customization that was done for each post in Jekyll, this step will require more or less effort. There are no hard and fast rules here except reviewing any errors running `hugo server` and comparing your site with the structure, config, and front matter from the unedited Wowchemy templates are your friends. Test your changes and fix errors as needed. - -## Publish -The default is for Jekyll to publish the website to a `_site` directory, whereas Hugo publishes to a `public` directory. - -## A practical example -Alexandre Normand migrated his website from Jekyll to Hugo in less than a day. You can see all his changes by looking at this GitHub [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610). However, bear in mind that this example is **not specific to the Wowchemy nor does it use the latest version of Hugo**. diff --git a/docs/en/import/migrate-from-wordpress.md b/docs/en/import/migrate-from-wordpress.md deleted file mode 100644 index 6c8fde57..00000000 --- a/docs/en/import/migrate-from-wordpress.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Migrate from Wordpress -linktitle: From Wordpress -date: 2017-12-03 -summary: Learn how to migrate your site from Wordpress to the Wowchemy website building framework for Hugo. ---- - -To migrate your website from Wordpress to Wowchemy is a two phase process: - -## Phase One - -First, install the [WordPress to Jekyll Exporter](https://wordpress.org/plugins/jekyll-exporter/) plugin into your Wordpress installation by following these steps: - -1. Place the [WordPress to Jekyll Exporter](https://wordpress.org/plugins/jekyll-exporter/) plugin in `/wp-content/plugins/` folder -2. Activate plugin in WordPress dashboard -3. Select `Export to Jekyll` from the `Tools` menu - -The WordPress plugin converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML with just a single click. A zip file will be generated, containing `_config.yml`, pages, and `_posts` folder containing `.md` Markdown files for each post. - -## Phase Two - -Given the Jekyll formatted contents of your generated zip file in the step above, proceed to follow the guide on [importing a Jekyll site into Wowchemy]({{< relref "migrate-from-jekyll.md" >}}). diff --git a/docs/en/import/rmarkdown.md b/docs/en/import/rmarkdown.md deleted file mode 100644 index 2314e5e6..00000000 --- a/docs/en/import/rmarkdown.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Import RMarkdown -linktitle: From RMarkdown -date: 2021-01-10 -summary: Learn how to write and import RMarkdown content from RStudio. ---- - -RMarkdown is a popular format with statisticians. It is often edited with RStudio and used to write technical blog posts or documentation that include snippets of the R statistical programming language. - -So how can we include R content in our Wowchemy site? - -# Prerequisites - -[Follow the guide to setup Wowchemy and Hugo on your computer]({{< relref "/docs/getting-started/install-locally" >}}). - -# Publishing content with RStudio - -First check that you have installed the prerequisites in the previous section. - -It's recommended to convert RMarkdown files directly to Markdown **without Blogdown** by using `render("input.Rmd", md_document())` or adding `output: md_document` to the file's front matter. - -Once the RMarkdown has been converted to Markdown (or HTML), Wowchemy and Hugo can then be used directly, as usual, such as with the command `hugo server`. - -# Alternatively: Using the Blogdown wrapper - -The RStudio team released Blogdown, a wrapper around Hugo for the RStudio IDE. However, users report that **Blogdown doesn't fully support modern Hugo versions**, with the RStudio team confirming these bug reports on GitHub. Therefore, it's not currently recommended to use Blogdown. Also, as Blogdown is an extra tool in the workflow, it can add unnecessary additional complexity to projects. - -1. Open [RStudio](https://www.rstudio.com/products/rstudio/) and install *Blogdown*: - - remotes::install_github('rstudio/blogdown') - -1. Open `academic.Rproj` from your site's folder, [downloading it if necessary](https://github.com/wowchemy/starter-academic/blob/main/academic.Rproj) - -1. Blogdown will automatically move your site's `config/_default/config.yaml` file to the site folder as [Blogdown does not support Hugo's config folder](https://github.com/rstudio/blogdown/issues/359) - -1. In the RStudio menu bar, choose **Addins > Serve Site** (clicking this button will call `blogdown:::serve_site()`) - - Paste the local URL which RStudio provides (e.g. http://127.0.0.1:4321) into your web browser to preview your new site - - Avoid using the integrated RStudio web browser as it can be outdated and buggy - -## RMarkdown vs Rmd - -It's recommended to save R content as Markdown with the **`.Rmarkdown` file extension** rather than as HTML with the `.Rmd` extension. - -Why is RMarkdown recommended? - -Hugo is used to convert Markdown content into an HTML website powered by a Wowchemy template and Wowchemy's page building components. Hence, by providing Rmd's HTML rather than processed RMarkdown as the input to Hugo and Wowchemy, you may experience conflicts as the Rmd ecosystem performs similar actions to Hugo yet has little awareness of Hugo and Wowchemy templates. diff --git a/docs/go.mod b/docs/go.mod deleted file mode 100644 index cb6815d0..00000000 --- a/docs/go.mod +++ /dev/null @@ -1,3 +0,0 @@ -module github.com/wowchemy/wowchemy-hugo-themes/docs - -go 1.15