diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f7259b0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +# Commit convention +This project follows the [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/#specification) with the following tags: +- `feat`: Added new feature +- `enh`: Improved working code +- `fix`: Fixed broken code +- `refac`: Moving/reformatting code without (intentionally) changing how it works, excluded from release notes unless it's a breaking change (`!`) +- `doc`: Changes to package documentation +- `test`: Changes to test suite +- `sys`: Systems administration (e.g. GitHub actions, packaging, etc.), generally excluded from release notes + +...and the following (optional) scopes: +- `[feat]`: Only affects code which has not yet been released, generally excluded from release notes +- `[silent]`: Always excluded release notes diff --git a/README.md b/README.md index 3c37fd9..5062d7d 100644 --- a/README.md +++ b/README.md @@ -7,3 +7,8 @@ Click [here](https://teparsons.github.io/mkdocs-landing/configuration/) for a fu # History Landing came out of me wanting to use mkdocs for [my own personal landing page](https://teparsons.github.io/mkdocs-landing#todd-parsons) - I made a custom .css file to sit alongside a generic mkdocs file and style it the way I wanted it. When implementing a [similar page for a friend](https://teparsons.github.io/mkdocs-landing#ben-ambrose) I realised that this basic structure could be fairly easily modified with a few key parameters to match a variety of different aesthetics. + +# Installation +Landing is [mirrored on PyPi](https://pypi.org/project/mkdocs-landing/) and can be installed via pip: + +`pip install mkdocs-landing` diff --git a/docs_src/configuration.md b/docs_src/configuration.md index bdb65f5..e0592f5 100644 --- a/docs_src/configuration.md +++ b/docs_src/configuration.md @@ -200,4 +200,7 @@ body_font_files: Image in the browser tab, should be a path to an image file, ideally a 16x16px .png file. ### `toc_level` -How many levels to include in a page-level table of contents? Use 0 to hide the table of contents altogether, use 1 to only show top level headings, use 2 to show top level headings and (when hovered) show the headings under each. \ No newline at end of file +How many levels to include in a page-level table of contents? Use 0 to hide the table of contents altogether, use 1 to only show top level headings, use 2 to show top level headings and (when hovered) show the headings under each. + +### `share_btn` +Whether or not to include a share () button in the top right of each page. Default is `true` (shown). \ No newline at end of file diff --git a/docs_src/links.md b/docs_src/links.md new file mode 100644 index 0000000..561d4ab --- /dev/null +++ b/docs_src/links.md @@ -0,0 +1,25 @@ +--- +title: Links +template: links.html +--- + +# Links pages + +Landing includes a page template for an array of links, similar to [LinkTree](https://linktr.ee/) or [Campsite](https://campsite.bio/). + +## Specify page as a links page +To specify any page on your site (including the homepage!) as a links page, just add the following in the [frontmatter](https://dev.to/dailydevtips1/what-exactly-is-frontmatter-123g) of the page: + +``` +template: links.html +``` + +## Add links + +In the links page, any links which are top level headings (`# [title](url)` in markdown) are styled like this: + +# [Landing](https://TEParsons.github.io/mkdocs-landing) + +You can also include an image within the link title (`# [![](image url) title](url)` in markdown) and it will be styled as a thumbnail: + +# [![](https://teparsons.github.io/mkdocs-landing/assets/branding/logo.png) Landing](https://TEParsons.github.io/mkdocs-landing) \ No newline at end of file diff --git a/mkdocs_landing/css/links.css b/mkdocs_landing/css/links.css new file mode 100644 index 0000000..830ea4c --- /dev/null +++ b/mkdocs_landing/css/links.css @@ -0,0 +1,37 @@ +/** +CSS unique to the links.html template +**/ + +main h1 { + margin: 0; +} + +main h1 > a { + border: 2px solid var(--crust); + border-radius: 1rem; + padding: 1rem 2rem; + margin-bottom: 2rem; + margin-top: 1rem; + margin-left: -1rem; + background-color: var(--base); + font-family: var(--body); + + display: grid; + grid-auto-flow: column; + justify-content: start; + align-items: center; + justify-items: start; + grid-gap: 2rem; +} + +main h1 > a:hover { + background-color: var(--mantle); +} + +main h1 > a img { + border: none; + margin: 0; + padding: 0; + min-width: 2em; + width: 2em; +} \ No newline at end of file diff --git a/mkdocs_landing/css/style.css b/mkdocs_landing/css/style.css index a6e7e5a..b802282 100644 --- a/mkdocs_landing/css/style.css +++ b/mkdocs_landing/css/style.css @@ -73,6 +73,20 @@ div#background-gradient { top: 0; bottom: 0; left: 0; right: 0; } +#share { + position: absolute; + right: 2rem; + top: 2rem; + font-size: 2rem; + padding: 1rem; + color: var(--crust); + border-radius: 100%; +} +#share:hover { + color: var(--text); + background-color: var(--crust); +} + /** Header **/ diff --git a/mkdocs_landing/links.html b/mkdocs_landing/links.html new file mode 100644 index 0000000..10c1a23 --- /dev/null +++ b/mkdocs_landing/links.html @@ -0,0 +1,31 @@ + + + +{% include "partials/head_config.html" %} + + + + +
+ {% if config.theme.share_btn %} + + + + {% endif %} + + {% include "partials/homepage_header.html" %} +
+ {{ page.content }} + +
+ + + + + \ No newline at end of file diff --git a/mkdocs_landing/main.html b/mkdocs_landing/main.html index 9664dfd..c31bcaa 100644 --- a/mkdocs_landing/main.html +++ b/mkdocs_landing/main.html @@ -1,10 +1,17 @@ + {% include "partials/head_config.html" %} +
+ {% if config.theme.share_btn %} + + + + {% endif %} {% if page.is_homepage %} {% include "partials/homepage_header.html" %} diff --git a/mkdocs_landing/mkdocs_theme.yml b/mkdocs_landing/mkdocs_theme.yml index 7fb77fc..21f8cb2 100644 --- a/mkdocs_landing/mkdocs_theme.yml +++ b/mkdocs_landing/mkdocs_theme.yml @@ -20,6 +20,7 @@ header_layout: - tagline - title - socials +share_btn: true content_box_opacity: 0% content_box_padding: 3rem background: "fixed center/cover var(--base)" diff --git a/mkdocs_landing/partials/head_config.html b/mkdocs_landing/partials/head_config.html index f5c07b5..6d42a4b 100644 --- a/mkdocs_landing/partials/head_config.html +++ b/mkdocs_landing/partials/head_config.html @@ -1,4 +1,4 @@ - + {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} \ No newline at end of file + diff --git a/pyproject.toml b/pyproject.toml index 140abf2..8809710 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "mkdocs-landing" -version = "0.0.6" +version = "0.0.7" authors = [ {name = "Todd Parsons", email = "todd.e.parsons@gmail.com"} ] @@ -13,6 +13,15 @@ dependencies = [ [project.optional-dependencies] tests = [ "pytest", + "httpx", + "pyyaml", + "mkdocs-get-deps", + "mkdocs-material", + "shot-scraper", + "jinja2", + "tqdm", + "uv", + "mkdocstrings-python", ] [project.urls] diff --git a/tests/test_sites/mkdocs_gallery/docs/index.md b/tests/test_sites/mkdocs_gallery/docs/index.md new file mode 100644 index 0000000..8a690fb --- /dev/null +++ b/tests/test_sites/mkdocs_gallery/docs/index.md @@ -0,0 +1,20 @@ +# Welcome to Landing + +This page is built with the [Landing](https://TEParsons.github.io/Landing) theme, +and demonstrates how a few Markdown extensions and MkDocs plugins +will look within this theme. + + +To install the theme: + +```bash +pip install mkdocs-landing +``` + + +To build your docs with this theme: + +```yaml +# mkdocs.yml +theme: landing +``` \ No newline at end of file diff --git a/tests/test_sites/mkdocs_gallery/docs/reference.md b/tests/test_sites/mkdocs_gallery/docs/reference.md new file mode 100644 index 0000000..9a4d91c --- /dev/null +++ b/tests/test_sites/mkdocs_gallery/docs/reference.md @@ -0,0 +1 @@ +::: calculator \ No newline at end of file diff --git a/tests/test_sites/mkdocs_gallery/mkdocs.yaml b/tests/test_sites/mkdocs_gallery/mkdocs.yaml new file mode 100644 index 0000000..a7d4f3c --- /dev/null +++ b/tests/test_sites/mkdocs_gallery/mkdocs.yaml @@ -0,0 +1,53 @@ +site_name: Landing +theme: landing + +docs_dir: docs +site_dir: ../../artefacts/test_mkdocs_gallery + +markdown_extensions: +- attr_list +- admonition +- footnotes +- pymdownx.blocks.admonition +- pymdownx.blocks.details +- pymdownx.blocks.tab +- pymdownx.emoji +- pymdownx.keys +- pymdownx.magiclink +- pymdownx.snippets: + check_paths: true +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format +- pymdownx.tasklist: + custom_checkbox: true + +plugins: +- search +- mkdocstrings: + handlers: + python: + paths: [src] + import: [https://docs.python.org/3/objects.inv] + options: + docstring_options: + ignore_init_summary: true + docstring_section_style: list + heading_level: 1 + inherited_members: true + merge_init_into_class: true + separate_signature: true + show_root_heading: true + show_root_full_path: false + show_source: false + show_signature_annotations: true + show_symbol_type_heading: true + show_symbol_type_toc: true + signature_crossrefs: true + summary: true + +nav: +- Home: index.md +- Python package docs: reference.md diff --git a/tests/test_sites/mkdocs_gallery/src/calculator.py b/tests/test_sites/mkdocs_gallery/src/calculator.py new file mode 100644 index 0000000..5e0d497 --- /dev/null +++ b/tests/test_sites/mkdocs_gallery/src/calculator.py @@ -0,0 +1,105 @@ +"""Provide several sample math calculations. + +This module allows the user to make mathematical calculations. + +Examples: + >>> from calculator import calculations + >>> calculations.add(2, 4) + 6.0 + >>> calculations.multiply(2.0, 4.0) + 8.0 + >>> from calculator.calculations import divide + >>> divide(4.0, 2) + 2.0 + +The module contains the following functions: + +- `add(a, b)` - Returns the sum of two numbers. +- `subtract(a, b)` - Returns the difference of two numbers. +- `multiply(a, b)` - Returns the product of two numbers. +- `divide(a, b)` - Returns the quotient of two numbers. +""" + +from __future__ import annotations + + +def add(a: int | float, b: int | float) -> float: + """Compute and return the sum of two numbers. + + Examples: + >>> add(4.0, 2.0) + 6.0 + >>> add(4, 2) + 6.0 + + Parameters: + a: A number representing the first addend in the addition. + b: A number representing the second addend in the addition. + + Returns: + A number representing the arithmetic sum of `a` and `b`. + """ + return float(a + b) + +def subtract(a: int | float, b: int | float) -> float: + """Calculate the difference of two numbers. + + Examples: + >>> subtract(4.0, 2.0) + 2.0 + >>> subtract(4, 2) + 2.0 + + Parameters: + a: A number representing the minuend in the subtraction. + b: A number representing the subtrahend in the subtraction. + + Returns: + A number representing the difference between `a` and `b`. + """ + return float(a - b) + +def multiply(a: int | float, b: int | float) -> float: + """Compute and return the product of two numbers. + + Examples: + >>> multiply(4.0, 2.0) + 8.0 + >>> multiply(4, 2) + 8.0 + + Parameters: + a: A number representing the multiplicand in the multiplication. + b: A number representing the multiplier in the multiplication. + + Returns: + A number representing the product of `a` and `b`. + """ + return float(a * b) + +def divide(a: int | float, b: int | float) -> float: + """Compute and return the quotient of two numbers. + + Examples: + >>> divide(4.0, 2.0) + 2.0 + >>> divide(4, 2) + 2.0 + >>> divide(4, 0) + Traceback (most recent call last): + ... + ZeroDivisionError: division by zero + + Parameters: + a: A number representing the dividend in the division. + b: A number representing the divisor in the division. + + Returns: + A number representing the quotient of `a` and `b`. + + Raises: + ZeroDivisionError: An error occurs when the divisor is `0`. + """ + if b == 0: + raise ZeroDivisionError("division by zero") + return float(a / b) \ No newline at end of file