Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README.md -> index.md should be optional #1580

Closed
Galarzaa90 opened this issue Aug 7, 2018 · 10 comments
Closed

README.md -> index.md should be optional #1580

Galarzaa90 opened this issue Aug 7, 2018 · 10 comments
Labels

Comments

@Galarzaa90
Copy link

@Galarzaa90 Galarzaa90 commented Aug 7, 2018

This is a really useful feature, but it should be optional.

I have a README.md file in my repository exclusively to render it on GitHub, indicating that the documentation uses format not compatible with GitHub, and that it should be viewed on the generated site.

See: https://github.com/Galarzaa90/NabBot/tree/master/docs

Now, I also have an index.md file in the docs folder, and that is the actual homepage of my site, and now it is getting overriden by README.md and there's no way to see the homepage anymore.

See:

And this is my pages/nav section:

nav:
    - Home: index.md
    - Changelog: changelog.md
    - Install Guide: install.md
    - Permissions: permissions.md
    - FAQ: faq.md
    - Features:
      - Overview: features/index.md
      - Autoroles: features/autoroles.md
      - Groups: features/groups.md
    - Commands:
      - Overview: commands/index.md
      - Admin commands: commands/admin.md
      - General commands: commands/general.md
      - Info commands: commands/info.md
      - Loot commands: commands/loot.md
      - Mod commands: commands/mod.md
      - Owner commands: commands/owner.md
      - Roles commands: commands/roles.md
      - Settings commands: commands/settings.md
      - Tibia commands: commands/tibia.md
      - TibiaWiki commands: commands/tibiawiki.md
      - Tracking commands: commands/tracking.md
    - Hosting:
      - Configuration: hosting/config.md
      - Messages: hosting/messages.md
      - Cogs: hosting/cogs.md

Full file: https://github.com/Galarzaa90/NabBot/blob/master/mkdocs.yml

@waylan
Copy link
Member

@waylan waylan commented Aug 7, 2018

How would you propose we determine which file to use? Only fall back to README.md if index.md is not present? Of did you have something else in mind?

And as a reminder, in version 1.0 the nav section of the config has no effect on which pages are included in the build. It only defines the global navigation menu. Therefore, it would have no effect on whether MkDocs should use README.md or index.md as the index file for a directory.

Loading

@Galarzaa90
Copy link
Author

@Galarzaa90 Galarzaa90 commented Aug 7, 2018

I think that could be the safest option. If index.md is present, then do not use README.md.

Loading

@waylan
Copy link
Member

@waylan waylan commented Aug 7, 2018

I'm not entirely sure how to implement this. Internally we build up a files collection which holds the data for each page. That collection would contain an object for each of the README and the index file. For example, using pseudo code, a collection might look like this:

[
    Page(src_path='index.md, dest_path='index.html', url='index.html'),
    Page(src_path='README.md', dest_path='index.html', url='index.html'),
    Page(src_path='about.md', dest_path='about.html', url='about.html')
]

The problem is that two different source pages both point to the same destination. And as we step through that collection, writing each file to the destination, the second file overwrites the first. Perhaps we should not include the README at all if there is an index? It would seem unlikely that the user would want the README to be included even if it was "hidden."

Loading

@waylan waylan added the Bug label Aug 7, 2018
@Galarzaa90
Copy link
Author

@Galarzaa90 Galarzaa90 commented Aug 7, 2018

And how is this collection ordered? If somehow, README.md always had precedence in the collection, even if it generated index.html, it would then be overwritten by the content of index.md.

I'm assuming this collection is just ordered from crawling the files in the docs directory, so hardcoding a different order for README.md is probably not a viable option.

And yes, this would mean not including README.md at all if there's also an index.md file. But who knows if someone actually wants both README.md and index.md.

Loading

@waylan
Copy link
Member

@waylan waylan commented Aug 7, 2018

We use our own sort function (within a directory) which sorts index files to the top so that an index file always comes first. All other files are sorted alphanumerically. The sort function does nothing special for readme files. So, currently the index file will always come before the readme file. Perhaps the simple fix would be to simply update the sort function to sort readme files before index files.

The other solution would be to exclude the readme if an index file is present.

Loading

@waylan
Copy link
Member

@waylan waylan commented Aug 7, 2018

Thinking about this more, it occurs to me that we promise that index files are sorted to the top. However, that is not true when the source of an index file is README.md. Therefore, sorting the README might actually fix two bugs.

Loading

@Galarzaa90
Copy link
Author

@Galarzaa90 Galarzaa90 commented Aug 7, 2018

Then I think sorting would be a good solution for this :)

Loading

waylan added a commit to waylan/mkdocs that referenced this issue Aug 8, 2018
@waylan waylan closed this in #1582 Aug 8, 2018
waylan added a commit that referenced this issue Aug 8, 2018
@Galarzaa90
Copy link
Author

@Galarzaa90 Galarzaa90 commented Aug 8, 2018

Thanks :), now just gotta wait for the next release 👍

Loading

@ppKrauss
Copy link

@ppKrauss ppKrauss commented Feb 24, 2020

Hi, please reopen, there are an error, seems a bug.

cd my_software_project_with_READMEs
mkdocs build --site-dir /var/www/mySite.org/docs

results in

INFO    -  Cleaning site directory
INFO    -  ...
WARNING -  Documentation file 'SubDocsFolder/etc.md' contains a link to 
          'SubDocsFolder/index.md' which is not found in the documentation files.

But SubDocsFolder/README.md exists (!). So, in that condiction mkdocs build is ignoring my README.md file


MOVED TO #2004

Loading

@waylan
Copy link
Member

@waylan waylan commented Feb 25, 2020

@ppKrauss please open a new issue.

Sent with GitHawk

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants