Update mkdocs.yml template for mkdocs 2.5+ #163
Conversation
| theme: material | ||
|
|
||
| pages: | ||
| - Home: index.md |
There was a problem hiding this comment.
Would it make sense to point this at the README.md file? There's a lot of overlap between the index.md and README.md templates (wrt general overview and requirements).
https://github.com/totten/civix/blob/master/src/CRM/CivixBundle/Resources/views/Code/readme.md.php
There are a few differences wrt to install-instructions, usage, known issues, and future plans - however, I think these differences are more happenstance than essence. Those topics all seem equally plausible as "quick intro material".
There was a problem hiding this comment.
It might make sense! At this point, I'm just trying to be consistent with the instructions at https://docs.civicrm.org/dev/en/latest/documentation/extensions/ .
In the README section on that page, it suggests that you might want to just make a symlink from README.md to docs/index.md. So I guess I'd want to leave this yml file as-is in any case, just start with a symlink.
There was a problem hiding this comment.
Without a file called "index.md" you won't get an autoloaded page when hitting the book. There needs to be at least one file called "index" at least at the moment.
There was a problem hiding this comment.
Thanks @MikeyMJCO! over in PR #162 (the version that should be mergeable before the docs infrastructure upgrade) I left index.md in place and just added the explanatory comment suggested below.
| @@ -0,0 +1,21 @@ | |||
| site_name: <?php echo "$fullName\n"; ?> | |||
There was a problem hiding this comment.
Maybe leave a trail pointing to some information about what how to use mkdocs? e.g.
| site_name: <?php echo "$fullName\n"; ?> | |
| ## Use mkdocs to generate a manual for this extension. For more information about mkdocs, | |
| ## see https://docs.civicrm.org/dev/en/latest/documentation/ | |
| site_name: <?php echo "$fullName\n"; ?> |
There was a problem hiding this comment.
Good call. I've updated it in PR #162, which just has the first commit introducing these files with the old mkdocs.yml extensions syntax. I'll rebase this one once that one gets merged.
ejegg
changed the title
|
This can be merged - current docs infra supports all of this. |
|
@totten see ^^ we should merge |
ejegg
changed the title
Just generates mkdocs.yml and docs/index.md with a couple of Template builders in the main InitCommand for now. Alternatively, could create a Docs builder and/or command. Uses the old markdown_extensions syntax because that's all the publishing infrastructure supports now. Fixes totten#161
Mikey says this'll have to wait for an update to the publishing infrastructure.
|
OK, this is rebased + title changed to remove DNM warning |
| repo_url: https://lab.civicrm.org/extensions/FIXME | ||
| theme: material | ||
|
|
||
| pages: |
There was a problem hiding this comment.
| pages: | |
| pages: |
The pages key is deprecated. It won't work. This should use nav:
|
See the example here: https://docs.civicrm.org/dev/en/latest/extensions/documentation/#config |
|
The file should have the |
The markdown_extensions syntax has changed, but the current publishing infrastructure doesn't support the new stuff yet. Splitting this into a separate PR