Implement a git repository button

[Bassetts]

This is an initial implementation of adding an optional git button as requested in #794. Just wanted to get this open to start the conversation.

I have intentionally kept it generic rather than making it GitHub specific. This allows it to be used for any git hosting service.

Todo:

• Add config option to specify which icon to display
  • Default to git icon if not specified.
  • FontAwesome 4.4 supports fa-git, fa-git-square, fa-github, fa-github-alt, fa-github-square. I personally feel the options provided should be git or github, ignoring the square and alt variants.
  • If we want to support GitLab then FontAwesome would need updating to at least v4.6.
• Update documentation and examples
• Update tests

[Michael-F-Bryan]

Thanks for the PR, @Bassetts!

What are your thoughts on having a git_repository_icon field which specifies the FontAwesome name for the icon to use (with fa-github by default)? That way we can use the GitHub icon by default, but if the user thinks something like code-fork is more relevant, they can set git-repository-icon = "fa-code-fork" in their book.toml.

In terms of documentation, it should be enough to add the corresponding bullet points and update the [output.html] example in config.md and in the user guide.

[Bassetts]

@Michael-F-Bryan My initial thought was to have an enum to restrict which icons can be selected, but I think you're right, we should just let the user decide.

If it is implemented this way then the functionality actually becomes quite generic as you could put any icon and any url into the config.

Maybe we should consider allowing the user to specify a list options for additional links and then we just render "additional links" in the right buttons area. This would allow for things like social media links to be added, but does add complexity. The user would have to provide the icon as there is no longer a sensible default, and we'd also need a value to be specified for the title attribute.

[Michael-F-Bryan]

Maybe we should consider allowing the user to specify a list options for additional links and then we just render "additional links" in the right buttons area.

Hmm... I'm just throwing around ideas here, but would that mean a user's book.toml could look like this:

[[output.html.links]]
title = "The GitHub Repository"
# the icon starts with `fa-` so assume it's FontAwesome
icon = "fa-github"
href = "https://github.com/my-user/my-repo"

[[output.html.links]]
title = "My Website"
# Parses as a URL, insert an `<img />` tag
icon = "https://example.com/my-logo.png"
href = "https://example.com/"

And we would then update the HTML config to look something like this:

struct HtmlConfig {
  ...
  /// Icons to be rendered across the top
  links: Vec<Link>,
}

struct Link {
  icon: Icon,
  title: String,
  href: Url,
}

enum Icon {
  FontAwesome(String),
  Url(Url),
}

impl Deserialize for Icon {
  // add appropriate logic for parsing a string as either 
  // a FontAwesome icon or a URL.
}

I think it'd be really cool, although perhaps something we should explore in a new issue, allowing this one to be merged in the meantime.

[Bassetts]

@Michael-F-Bryan I will finish up the current implementation over the next few days (hopefully today).

I like the idea of allowing the user to provide multiple links as it makes this really flexible, and I'd definitely like to explore that option.

[Bassetts]

@Michael-F-Bryan This is now complete. I have added the git-repository-icon option to the config and it defaults to fa-github, updated the documentation and also added to the config tests for the new options.

I have also updated the FontAwesome version to 4.7.0 as this the latest in the 4.x releases, and includes the fa-gitlab icon.

[Michael-F-Bryan]

Merged!

Sorry for leaving it so long @Bassetts, I didn't notice the PR was ready to be merged.

[Bassetts]

No worries at all. Now this is complete I will open a new issue to explore the additional link functionality that we briefly discussed earlier @Michael-F-Bryan.

[theduke]

This is not documented in https://rust-lang-nursery.github.io/mdBook/format/config.html.

[termoshtt]

git_repository_url: A url to the git repository for the book. If provided an icon link will be output in the menu bar of the book.
git_repository_icon: The FontAwesome icon class to use for the git repository link. Defaults to fa-github.

This document is wrong. It should be git-repository-url and git-repository-icon (use - instead of _ in book.toml)

[ehuss]

The documentation has been updated, just waiting for a new release to publish it.