facebook / facebook/docusaurus

Warning or error for orphan docs

Đang mở
#2,875 13 bình luận 2 reaction 1 người được giao Được @slorber nhận Xem trên GitHub
domain: dx feature
Ngôn ngữ chính
TypeScript
Star
66.2k
Fork
10k
Merge trung bình
1 ngày 3 giờ
Pull request đã merge (30 ngày)
52

Mô tả

## 🚀 Feature

When the site is built, show a warning or an error about orphaned docs page. An orphaned doc would be the one that has no links from any other docs or in the sidebar navigation. As a result, that doc may never be discovered.

### Have you read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md#reporting-new-issues)?

Yes

## Motivation

This is one of the ways to improve seo for a technical docs site. All docs pages should be navigateable through internal links in the site. In this case, it can be either through links from another doc or through sidebar navigation.

Sphinx based site has an option to be able to detect this kind of orphaned docs. It'd be great if we could catch similar issues in Docusaurus.

https://docs.readthedocs.io/en/stable/guides/technical-docs-seo-guide.html

## Pitch

I think the easiest way to implement is to check if each docs listed in one of the sidebar.

Whether each docs have at least one link from another doc, might be tricky to implement because every docs have to parsed and keep track of links. It's probably also safe to assume that every docs should be in the sidebar. So, maybe only checking sidebars for orphaned docs is enough.

This should be configurable so that it'll be either an error or warning. Making it an error will be helpful for CI process.

A similar warning for orphaned assets can be helpful. There's no point in having an image file included in the site if it's not used anywhere in the docs. Perhaps orphaned docs asset should be a separate feature request.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.