Add: Refactored where the menu is configured, and added a tools secti…

…on in the Community page (#114)

docs/community/community-services.md → docs/community/index.md

@@ -1,19 +1,29 @@
-# Community Services
-
+---
+collapse: nav
+---
+# Community tools and services
 
 !!! info "Obligatory disclaimer"
 
-    Please note that the table below contains a list of community services that are not officially supported by CCP Games. We acknowledge the hard work and dedication of the developers who have created these services and give them a soapbox to promote their services. However, we do not endorse or guarantee the services listed below. If you have any questions or concerns about a service listed below, please contact the service creator directly.
+    Please note that the table below contains a list of community projects and services that are not officially supported by CCP Games. We acknowledge the hard work and dedication of the developers who have created these services and give them a soapbox to promote their services. However, we do not endorse or guarantee the services listed below. If you have any questions or concerns about a service listed below, please contact the service creator directly.
 
+# Services
 
 | Service Name                                        | Creator                                                                                             |
 | --------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
 | [Sample Service](./sample-service/index.md)         | [:octicons-mark-github-16: Developer McDeveloperface](https://github.com/@your-username-here)       |
 
 
+# Other tools and resources
+
+| Name                                            | Description                    | Creator                                                                                       |
+| ------------------------------------------------| ------------------------------ | --------------------------------------------------------------------------------------------- |
+| [Sample Tool](https://github.com/esi/esi-docs)  | Crowd-sourced documentation    | [:octicons-mark-github-16: Developer McDeveloperface](https://github.com/@your-username-here) |
+
+
 # Submitting a Service
 
-If you would like to list your service here, please submit a pull request to this repository, adding your service to the table above, and creating a sub-page in this directory with more information about your service.
+If you would like to list your service here, please submit a pull request to this repository, adding your service to the table above, and creating a sub-page in this directory with more information about your service. Use the file in `src/docs/community/sample-service/` as a template.
 
 ## Requirements
 
@@ -25,36 +35,9 @@ If you would like to list your service here, please submit a pull request to thi
 
 As always, we reserve the right to remove any service from this list at any time for any reason, or decline to add a service to this list.
 
-## Service page template
-
-```markdown title="src/docs/community/your-service-name/index.md"
----
-search:
-  exclude: true
----
-
-# <Name of your service>
-
-## Description
-
-A brief description of your service.
-
-## Features
-
-A short feature showcase of your service.
-
-## Links
-
-- [:octicons-browser-16: Website](https://example.com)
-- [:octicons-mark-github-16: GitHub](https://github.com/esi/esi-docs)
-- [:simple-discord: Discord](https://discord.gg/eveonline)
-- [:simple-x: Twitter](https://twitter.com/eveonline)
-- [:simple-reddit: Reddit](https://reddit.com/r/eve)
-```
-
 !!! note "A note about search"
 
-    You might have noticed the search exclusion marker in the template above.
+    You might have noticed the search exclusion marker in the template file.
 
     This part is required.
 
@@ -65,4 +48,12 @@ A short feature showcase of your service.
 
 ## Adding images to your service page
 
-If you want to add images to your service page, be sure to add them to the same directory as your service page. Please keep the images small and optimized for the web, no larger than 250KB or 1024x768 pixels.
+If you want to add images to your service page, be sure to add them to the same directory as your service page. Please keep the images small and optimized for the web, no larger than 250KB or 1024x768 pixels. Also try to limit the amount of images you use on a single page, preferably no more than 10 unless necessary.
+
+# Submitting a tool or resource
+
+If you would like to list your tool or resource here, please submit a pull request to this repository, adding your tool or resource to the table above. Please keep the description of your tool or resource brief and to the point. If your tool or resource is big enough that you feel it needs its own page, this can be arranged, but please have a discussion about this on [discord](../support.md).
+
+## Tools vs. Services
+
+The general rule of thumb is that if your project is something that a developer would use to build something else, it's a tool or a resource. If it's something that an end user would use directly, i.e. by installing it themselves, or through something already hosted, it's a service.

docs/community/sample-service/index.md

@@ -1,6 +1,8 @@
 ---
 search:
   exclude: true
+
+title: Sample Service
 ---
 
 # EVE Online Sample Service

docs/index.md

@@ -1,3 +1,6 @@
+---
+collapse: nav
+---
 # EVE Third Party Developer Documentation
 
 This documentation is intended for software developers who are interested in creating third-party tools and applications for EVE Online. Whether you're building simple utilities, complex integrations, or just experimenting, this documentation will help you get started.

docs/menu.md

@@ -0,0 +1,12 @@
+* Home
+    * [Welcome](index.md)
+    * [Resources](resources/index.md)
+    * [Support](support.md)
+    * [ID Ranges](resources/id-ranges.md)
+* Services
+    * services/*/index.md
+* Guides and Examples
+    * [Useful Formulae](guides/useful-formulae.md)
+    * [PI](guides/pi.md)
+* [Community](community/index.md)
+    * community/*/index.md

docs/resources/index.md

@@ -1,3 +1,6 @@
+---
+collapse: nav
+---
 # Developer license agreement
 
 The developer license agreement must be signed before you can create third party applications. If you wish to re-read the agreement, you can do so [here](/license-agreement)

docs/services/esi/index.md

@@ -1 +1,4 @@
+---
+title: ESI
+---
 # EVE Swagger Interface (ESI)

docs/services/image-server/index.md

@@ -1,3 +1,6 @@
+---
+title: Image Server
+---
 # EVE Image Server (EIS)
 
 The EVE Image Server provides a way to retrieve/use images from EVE Online in your applications.

docs/services/sde/index.md

@@ -1 +1,4 @@
+---
+title: Static Data Export
+---
 # Static Data Export (SDE)

docs/services/sso/index.md

@@ -1,3 +1,6 @@
+---
+title: Single-Sign-On
+---
 # Single-Sign-On (SSO)
 
 The EVE single Sign-On (SSO) Service helps facilitate third-party application access for players.

mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: Documentation
+site_name: EVE Developer Documentation
 site_url: !ENV [SITE_URL, 'https://developers.eveonline.com/docs/']
 
 repo_url: !ENV [GITHUB_REPO_URL, 'https://github.com/esi/esi-docs']
@@ -8,23 +8,8 @@ edit_uri: edit/main/docs/
 hooks:
   - scripts/generate-snippets.py
 
-nav:
-  - Home: 
-    - Welcome: index.md
-    - Resources: resources/index.md
-    - Support: support.md
-    - ID Ranges: resources/id-ranges.md
-  - Services:
-    - "ESI": services/esi/index.md
-    - "Image Server": services/image-server/index.md
-    - "Static Data Export": services/sde/index.md
-    - "Single-Sign-On": services/sso/index.md
-  - Guides and Examples:
-    - Useful Formulae: guides/useful-formulae.md
-    - PI: guides/pi.md
-  - Community: community/community-services.md
 not_in_nav: |
-  community/*/index.md
+  community/sample-service/index.md
 
 theme:
   name: material
@@ -150,6 +135,8 @@ plugins:
   - search
   - tags
   - open-in-new-tab
+  - literate-nav:
+      nav_file: menu.md
   - privacy:
       assets: false
   - macros:

overrides/main.html

@@ -32,13 +32,9 @@
 {%- block site_nav -%}
 <!-- Navigation -->
 {%- if nav -%}
-  {% if page.meta and page.meta.hide %}
-    {% set hidden = "hidden" if "navigation" in page.meta.hide %}
-  {% endif %}
   <div
     class="esi-sidebar md-sidebar md-sidebar--primary"
     data-md-type="navigation"
-    {{ hidden }}
   >
   {% include "partials/sidebar-nav.html" %}
   </div>

overrides/partials/sidebar-nav.html

@@ -2,6 +2,29 @@
   {{ item.title }}
 {%- endmacro -%}
 
+{%- macro classes(item) -%}
+  {%- if item.children -%}
+    {%- set first = item.children | first -%}
+    {%- if first -%}
+    {%- if
+      (first.meta and first.meta.hide and "navigation" in first.meta.hide and not first.active)
+      or
+      (first.file and first.file.inclusion == first.file.inclusion.NOT_IN_NAV)
+    -%}
+    esi-nav-item-hidden
+    {%- endif -%}
+    {% endif %}
+  {%- else -%}
+    {%- if 
+    (item.meta and item.meta.hide and "navigation" in item.meta.hide and not item.active)
+    or
+    (item.file and item.file.inclusion == item.file.inclusion.NOT_IN_NAV)
+    -%}
+    esi-nav-item-hidden
+    {%- endif -%}
+  {%- endif -%}
+{%- endmacro -%}
+
 {%- macro render_toc_item(item, level = 1) -%}
   <li>
     <a class="md-nav__link" href="{{ item.url }}">{{ title(item) }}</a>
@@ -16,7 +39,7 @@
 {%- endmacro -%}
 
 {%- macro render_toc(item) -%}
-  {%- if item.active and not item.children and item == page -%}
+  {%- if item.active and item == page -%}
     {% set toc = page.toc %}
     {% set first = toc | first %}
     {% if first and first.level == 1 %}
@@ -46,12 +69,17 @@
 {%- macro render_sublevel(item) -%}
   {%- if item.active -%}
     {%- if item.children -%}
+      {%- set first = item.children | first -%}
       <ul class="esi-sidebar-nav esi-sidebar-nav-sublevel">
       {%- for subitem in item.children -%}
-        <li class="esi-sidebar-nav-item {% if subitem.active %}esi-sidebar-nav-item-active{% endif %}">
+      {%- if subitem.file and subitem.file.inclusion and subitem.file.inclusion == subitem.file.inclusion.NOT_IN_NAV -%}
+      {%- elif subitem.meta and subitem.meta.collapse and "nav" in subitem.meta.collapse and first == subitem -%}
+      {%- else -%}
+        <li class="esi-sidebar-nav-item {{ classes(subitem) }}{% if subitem.active %} esi-sidebar-nav-item-active{% endif %}">
           {{ render_item(subitem) }}
           {{ render_sublevel(subitem) }}
         </li>
+      {%- endif -%}
       {%- endfor -%}
       </ul>
     {% else %}
@@ -66,7 +94,7 @@
       {% set item = page %}
     {% endif %}
   {% endif %}
-  <li class="esi-sidebar-nav-item {% if item.active %}esi-sidebar-nav-item-active{% endif %}">
+  <li class="esi-sidebar-nav-item {{ classes(item) }}{% if item.active %} esi-sidebar-nav-item-active{% endif %}">
     {{ render_item(item) }}
     {{ render_sublevel(item) }}
   </li>

requirements.txt

@@ -1,5 +1,6 @@
 mkdocs==1.6.1
 mkdocs-get-deps==0.2.0
+mkdocs-literate-nav==0.6.1
 mkdocs-macros-plugin==1.3.7
 mkdocs-material==9.5.50
 mkdocs-material[imaging]==9.5.50