Skip to content

Latest commit

 

History

History
174 lines (115 loc) · 6.03 KB

README.md

File metadata and controls

174 lines (115 loc) · 6.03 KB
Raw

Loop Docs

This is the repo that contains the source files for the Loop Docs site.

Contributing

The easy way:

  • To suggest changes, please review Issues. Add your comment if an Issue is already open, otherwise, add a new Issue.
  • If it is a simple typo or wording change, follow the instructions in this video to submit a pull request the easy way.

If it is a more substantive change and you want to make a fork and provide pull requests, please keep reading.

Previewing Changes

To preview your work as you edit you must set up two python packages that are used to create this site using MkDocs. They are mkdocs, and mkdocs-bootswatch.

Review Properly Installing Python for help getting Python installed. MkDocs works with Python 2.7, 3.3-3.6, and pypy.

  • Install python modules
$ cd <loopdocs project location>
$ pip install -r requirements.txt
  • Run mkdocs server locally
$ cd <loopdocs project location>
$ mkdocs serve
  • Preview docs in browser. Most changes will update automatically as you edit. Configuration and navigation changes will require restarting the mkdocs server.
  • Optionally, you can share the preview with others by uploading them to your repository's gh-pages branch
$ mkdocs gh-deploy

Note that these two branch names: working-docs and master will automatically be published to your personal repository gh-pages by github actions when they are pushed to the github server.

Conventions

Links

Links should be written like this:

In the same directory: Click here for [Update FAQs](update-faqs.md)

In a directory below the current page: Click here for [Update FAQs](faqs/update-faqs.md)

In a directory "outside" the current directory: Click here for [Update FAQs](../faqs/update-faqs.md)

Like above, but linking directly to a heading/anchor in update-faqs.md:

Click here for [When Should You Update?](../faqs/update-faqs.md#when-should-you-update)

Notice about mkdocs: "Using absolute paths with links is not officially supported. Relative paths are adjusted by MkDocs to ensure they are always relative to the page. Absolute paths are not modified at all. This means that your links using absolute paths might work fine in your local environment but they might break once you deploy them to your production server."

Do NOT use a link starts that with a '/': Click here for [Update FAQs](/faqs/update-faqs.md)

Images

The conventions for linking to images is the same as linking to pages as described above.

New images should be placed in the "img" directory just below the md-file.

Example of correct link to image is [alt-text](relative path/image-name).

![iPhone](img/phones.png)

With images it is possible to add extra attributes like 'width' and 'center'.

![iPhone](img/phones.png){width="300"}

This will get rendered to this: <img alt="iPhone" src="img/phones.png" width="300">

You can also center a image, by adding '{align="center"}' on a new line
just below the paragraph you want to center:

![Eros](img/eros.png){width="750"}
{align="center"}

This will get rendered to this:
<p align="center">
    <img alt="Eros" src="../img/eros.png" width="750" />
</p>

A note about images in tables. Use html on the first line that indicates the table. For example, in displays.md there are many icons with descriptions to the right. This format provides appropriate views on both desktop and mobile.

For no header row, replace ||| with:

| <div style="width:72px"></div> ||
|---|---|
|![icon alt-text ](img/icon)|text with description|

To add header row, use:

| <div style="width:72px">Column 1</div> | Column 2 |

Admonitions and CSS

Now using the standard set of admonitions and CSS styles that come with the Material theme.

The admonitions in use are: First 3 boxes for Build Pages:

  • info
  • abstract
  • question

To get a warning triangle, use warning

To get a red zag icon, use danger

To get a pencil icon, use note

Admonition is a markdown extension that enables formatted blocks for visually calling out information.

The markdown syntax used by loopdocs is:

!!! keyword ""
    If a blank title is provided, no title is applied.
    Every indented line is included in the "box" created by this admonition

!!! keyword "Title String"
    If an explicit title string is provided, that is used as the title.
    The displayed title string matches the capitalization provided.

    Every indented line is included in the "box" created by this admonition

Copy Button

The copy-to-clipboard button is built into the Material theme for every code block and displayed on the right side.
When clicked it copies the content of the block into the clipboard.
However we chose to disable it by default for all code blocks and enable it on a case by case basis.
Here is how to enable the copy-to-clipboard button for a "code" block containing regular text.

``` { .txt .copy "title of this code block" }
Content of the code block here
```

where:

  • .txt denotes the language used in the content of the code block.
    For instance use .txt for regular text, .sh for a shell script, .bash for a Bash script. This is a required parameter. Here is the list of [supported languages](https://pygments.org/languages/) (use one of the Short Name`s).
  • .copy shows the copy-to-clipboard button when present (hidden otherwise)
  • title=“title of this code block” adds a title to the code (none by when absent)

Do note that:

  • There is a space before and after the opening curly brace {.
  • There is space before the closing curly brace }.

Source