Update docs for mkdocs & readthedocs optimization

[yu-ta-sato]

Description

This pull request introduces several improvements to the documentation and configuration for the City2Graph project. The main changes include enhanced SEO and social sharing metadata, integration with ReadTheDocs versioning, and improved handling of MkDocs and YAML syntax in the pre-commit configuration. Additionally, API documentation pages now include relevant keywords for better searchability.

Documentation and SEO Enhancements:

• Added custom Open Graph and Twitter Card meta tags for improved SEO and social sharing by overriding the default HTML template in docs/overrides/main.html.
• Updated all API documentation pages (e.g., docs/api/data.md, docs/api/graph.md, etc.) to include keywords metadata for better discoverability and search engine optimization. [1] [2] [3] [4] [5] [6] [7] [8]
• Added keywords metadata to docs/contributing.md and docs/installation.md for improved search relevance. [1] [2]

ReadTheDocs and MkDocs Integration:

• Updated mkdocs.yml to use an environment variable for site_url, allowing dynamic canonical URLs for different ReadTheDocs versions.
• Added a custom JavaScript file (docs/javascripts/readthedocs.js) to enhance ReadTheDocs integration, including a version selector and improved search behavior.
• Registered the new script in the extra_javascript section of mkdocs.yml.

Pre-commit and YAML Configuration:

• Updated .pre-commit-config.yaml to exclude mkdocs.yml from certain YAML checks, accommodating MkDocs-specific syntax. [1] [2]

Other Improvements:

• Disabled the social plugin in mkdocs.yml in favor of the new custom Open Graph meta tags, improving compatibility and reducing dependencies.

Related Issues

NA

Checklist

• I have read the Contributing Guide.
• I have updated the documentation, if necessary.
• I have added tests to cover my changes.
• All new and existing tests passed.
• Pre-commit checks passed locally.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!