Skip to content
This repository has been archived by the owner on Sep 20, 2023. It is now read-only.

add: docfx 101 #453

Open
CouldBeThis opened this issue Nov 29, 2020 · 0 comments
Open

add: docfx 101 #453

CouldBeThis opened this issue Nov 29, 2020 · 0 comments

Comments

@CouldBeThis
Copy link
Contributor

In the process of creating #452 I read readme.md closer but thought better to make a separate issue since it is somewhat tangential.

The section Getting Started, which immediately precedes Linting in the readme, provides some info about DocFX (added in #113).

This is something else unfamiliar to me... if I understand properly it is an extension on plain MD. It is used on the documentation site as served. Looks like it is not displayed on gh (example index.md: many links missing in gh preview are present on actual site).

Questions:

  1. Why? My impression is that this system is much more robust than regular MD. The motivation for using it for this particular project is not clear to me.
  2. Consistency? It is not clear to me if use of this system is mandatory or not. Seems like it would become quite messy if people are using different methods of md? (Which appears to be happening.)
  3. How? I am sorry to report that the provided docs are not very meaningful to me... they are way over my head. Specifically:
    1. How here? - Is there any explanation about how DocFX is implemented on this particular site? I doubt every feature is being used here. Is there a briefer explanation of just what is needed?
  4. Linting? does this relate to linting? I ran markdownlint **/*.md --ignore node_modules --ignore src in my local cloned jellyfin-docs without installing DocFX but the index.md did not produce errors as I expected for the special code. Will all DocFX pass regular md linting without problem?
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Development

No branches or pull requests

1 participant