You are browsing a read-only backup copy of Wikitech. The primary site can be found at wikitech.wikimedia.org

Developer Portal: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>Alex Paskulin
(Add doc links convention)
imported>Aklapper
(+{{ptag|Wikimedia-Developer-Portal}})
Line 1: Line 1:
{{ptag|Wikimedia-Developer-Portal}}
The Developer Portal is a central entry point for Wikimedia technical documentation.
The Developer Portal is a central entry point for Wikimedia technical documentation.



Revision as of 11:06, 25 January 2022

The Developer Portal is a central entry point for Wikimedia technical documentation.

View the demo Browse the repository

About the Developer Portal

The Developer Portal is a static site using MkDocs and Material for MkDocs. It uses a custom plugin to generate PO files and integrate with translatewiki.net. The Developer Portal is currently in development. For more information about the project, visit the page on mediawiki.org.

How it works

Rendering page content

The purpose of the Developer Portal is to help users find key documentation pages. The site is designed to make it easy to remix documentation links into new pages tailored for different purposes. Data in the Dev Portal is organized into three types of data:

  • documents: In /data/documents, YAML files describe key documents. Each document is assigned to one or more categories.
  • categories: In /data/categories, YAML files describe categories. Behind the scenes, the /macros/__init__.py macro builds categories and corresponding documents.
  • markdown files: Markdown files reside in /src subdirectories that correspond to the top-level sections of the dev portal site. Jinja template syntax inside those markdown files pulls in content from the categories.

Rendering the navigation

The Material theme for Mkdocs generates navigation sections based on the documents in a given subdirectory. It renders tables of contents based on the structure of an individual markdown file (its headings).

The navigation.indexes setting in mkdocs.yml implements section index pages. This causes the index.md file for a directory to be used as the landing page for a section. We use this feature because our index.md files (in /src) only include links to the other pages in the directory, so we don't need or want them to be displayed as an additional item to click in the left nav.

While it could be simpler to use a single markdown file for each site section, and rely on the TOC for navigation, this has drawbacks:

  • The TOC disappears on small screens, effectively removing navigation to key subsections.
  • Using multiple markdown files enables navigation through and between site sections via buttons at the bottom of the screen. This is a nice additional navigation option to supplement the left and/or horizontal menus.
  • Using a single index.md file populated via YAML for each site section means that nearly all the site structure will be rendered via YAML and templates. This means a larger number of YAML files, and a more difficult structure to understand if you're encountering the site for the first time. It's easier to understand how the site is rendered -- and thus better for future maintainers -- when more of the structure is coming from markdown and less from YAML and Jinja magic.

For more details about why we made these implementation decisions, see this Miro board (restricted access).

How to use it

The Material theme for Mkdocs renders content in ways that can be confusing due to our usage of templates to generate page content based on yaml docs and categories (see the /data subdirectory).

This section describes the content requirements that doc editors and creators must follow in order for the site to render correctly and consistently.

Hide TOC in subdirectory index files

index.md files in subdirectories of the /src directory must hide the table of contents. This is necessary because the content of most of these pages is navigational: the section headers in the page mirror the list of other pages in the directory/navigation section, so the navigation and the table of contents render the same content. This is only true for subdirectories of the /src directory–not for the top-level index.md nor for any other markdown files.

To hide the table of contents, include the following at the top of the index.md file:

---
hide:
  - toc
---

Mirror text copy in index files and category files

In general (but not always), each section (##) in a subdirectory index.md file should contain:

  • A text snippet that is the same as the category description used in the Jinja template on the subpage to which that section links
  • A link to another md file (subpage) in that directory

Render categories

To render a category and its assigned documents, add this syntax to a markdown file.

Render one category per page:

{{ category.render( "category-name-here" ) }}

Render multiple categories per page:

{{ category.render( "category-name-here", 2 ) }}

Order documents in a category

To control the order that documents appear in a category, use this syntax in the document YAML definition:

categories:
    category-a: 1
    category-b: 2
    category-c: 0

In this example, the document will be ordered first in category-a, second in category-b, and unordered in category-c. Note that if a document needs to be ordered in any of its category, all listed categories must use the dictionary syntax instead of the list syntax (category-a: 1 instead of - category-a).

If a category contains both ordered and unordered documents, the unordered documents are listed first since their index is 0.

Content conventions

  • In most cases, documentation links should link to the top of the page, not to a specific section. Exceptions include linking to specific endpoints or endpoint groups in an OpenAPI specification or in cases where it is not possible to break up a long page.
  • All documentation links should be stored in data/documents, not in markdown files, with the exception of the intro on the site homepage.