meteor / meteor-theme-hexo

The framework we use for docs.

Usage

The theme is available on npm as meteor-theme-hexo. The theme can be used by either:

1. (preferred) Installing the theme from npm and allowing dependency auto-update tools, like @renovate-bot or @greenkeeperio-bot, to update the npm for you. This requires you to set the theme in your _config.yml as ../node_modules/meteor-theme-hexo; or
2. (less ideal) Cloning this repository into the doc deployment's themes/meteor directory and referring to the theme in that deployment's _config.yml as just meteor. This will require you to update the theme (or at least its submodule) manually!

Developing

In order to develop this theme, you should:

1. Check out this (meteor-theme-hexo) repository.

2. Check out the theme-example docs deployment alongside the meteor-theme-hexo directory.

3. Check out either (apollo-hexo-config or meteor-hexo-config) alongside the meteor-theme-hexo directory. This will leave you with something like:

   Dev/
   ├── meteor-theme-hexo/
   ├── meteor-hexo-config/ (or apollo-hexo-config/)
   └── theme-example/
   

4. Run npm install in the meteor-theme-hexo

5. Switch to the theme-example directory.

6. Run npm install

7. Inside theme-example, run:

   npm start -- --config-dir ../apollo-hexo-config --theme-dir ../meteor-theme-hexo
   

   (or meteor-hexo-config, if working on the Meteor theme!)

For more information, check the README.md on theme-example.

Docs docs

There are docs docs for help with docs deployments! Please read them (and help update them on their own repository if they're wrong!).

Known deployments

Important: Please submit a PR to update this list when making new deployments to ensure they receive important PRs (such as dependency and repo consistency updates).

[0]	GitHub Repo	Deployment URL 🚀
☺️	meteor/guide	https://guide.meteor.com/
☺️	meteor/docs	https://docs.meteor.com/
☺️	meteor/galaxy-docs	https://galaxy-guide.meteor.com/

^[0] Equipped with auto-update dependency management, so you don't need to make sure the theme is updated.

If a change to this theme is made, it should be re-published to npm. Those repos using submodules should update their submodule reference to the latest tip and those using the meteor-theme-hexo npm package should update that dependency to the latest published version.

meteor-theme-hexo's Issues

Change default menu scrollTop?

Right now, after pageload, it's set to:

A little higher would look nicer to me:

[feature] Broken link checker

It would be great if we had a plugin which automatically failed the build if we've introduced a broken link.

As originally submitted in https://github.com/apollographql/engine-docs/pull/138 by @evans, but with the intention of having it affect all of our docs repositories, not just apollographql/engine-docs.

Render all pages on one page

There'd be a few benefits of this:

1. Can use browser search
2. Entire sitemap in the sidebar
3. Can print for PDF for offline mode

What's needed:

• Figure out a way to get hexo to render all pages at one route. Maybe there's a plugin for it? (I searched and didn't find one)
• Update our main.js code to handle the multi-page case (I think right now it would put all sub menu items under the first top-level menu item.
• Ensure the "all page" is not indexed by google.

Happy to advise if someone wants to have a go at this.

“Edit on GitHub” button is broken on version branches.

As discovered on the “v2” (version 2) apollo-server documentation:

https://www.apollographql.com/docs/apollo-server/v2/

Can't test Algolia locally

Currently, there's no way to test the search functionality locally.

Millenials test everything locally and are confident that nothing will break in production. We should figure out a way to make this happen soon!

.content doesn't extend to bottom of screen on mobile

.content is bottom: 0 yet doesn't extend to bottom

Can replicate in Chrome:

cc @unicodeveloper

Allow opening menu with swipe on mobile

Currently you can close menu by swiping it closed, but you can't swipe it back open – you have to tap top-left icon

Place the current Meteor Version in the docs

@dominicnguyen i am not quite sure if i got this right to place visual feedback for the docs here.
As i read in the forums something about Metoer 1.3.3 i was looking to find the current meteor version. This was placed very prominent on the old docs page. I was looking on the homepage and the github page without a fast result. I think the docs are a good place for that kind of info.

Maybe we could just place it beside Meteor API Docs in the sidebar. What do you think?

[New Nav] Unvisited links are blue

https://www.dropbox.com/s/6yho2lymjd6farv/Screenshot%202016-09-01%2014.35.19.png?dl=0

Styling issue in code snippets with no specified language

https://www.dropbox.com/s/jcb0ikwdycdedvv/Screenshot%202016-08-27%2012.14.10.png?dl=0

Sometimes menu doesn't complete open/close animation

when swiping menu closed in iOS Chrome, sometimes it stops where you take your finger off the screen, instead of continuing to an open/closed position

Remove Lodash

In Hexo 5+ Lodash is no longer available in the Hexo API.

https://hexo.io/news/2020/07/29/hexo-5-released/#Breaking-change

Links and Code look the same

Code used to have a background color to differentiate it 😢

@abernix might have some idea?

Display the nav_links in the mobile menu

Hi! 👋

First of all, thank you for open sourcing this docs theme. We've used it in Front-Commerce's documentation and it is really great!

However, I've noticed that there's an issue when displaying the nav_links on mobile. They should appear above the sidebar but are hidden behind the header. It is displayed correctly though when you start in desktop mode and resize to mobile.

This can be seen in Apollo Docs : https://www.apollographql.com/docs/

We've made a fix on our side, but I'm not sure that the PR would be OK for you since our fix uses flexbox and I've noticed that it does not seem to appear in your codebase. If it's OK for you though, I could make a PR later on.

Our fix: front-commerce/developers.front-commerce.com@c122803
A working preview: https://deploy-preview-18--elastic-austin-cf9d40.netlify.com/docs/

Default rendering for markdown doesn't match GitHub README

By default we have the marked.breaks config set to true, which matches the way github renders comment markdown, but not README markdown. Since these files are more likely to be viewed in that way, we should probably set marked.breaks: false by default in the theme.

See this commit: apollographql/apollo-link@f6be768

Further differentiate h2s and h3s

From meteor/guide#463 (comment)

Think one of the reasons for suggesting darker anchors was for them only to be on h2s (atm on all) to help differentiate from h3s. I was confused reading the first page of

http://guide.meteor.com/ui-ux.html

because I didn't notice that "view layers" was a different size from "syntax". Perhaps also font weight and/or size.

h5 is really small compared to body and don't have links in the sidebar

Take a look at https://www.apollographql.com/docs/link/links/rest.html

Report error after installing

I run hexo s. The websit is running but Terminal reports Error: Cannot find module './build/Release/DTraceProviderBindings' error.

Theme License

Apologies for spamming your issue board. But I've been working with Meteor for a while now and everytime I check the guide or docs i think how slick the hexo theme is. What's the license on the meteor hexo theme?

[mobile] Menu click target too small

It can be difficult to register a touch on the menu open button.

License?

Hi! I am looking to convert a docs site for my existing open-source project and would love to use this as a starting point, as that is what it is set up for - and it's awesome! The project is non-competitive with meteor. Is that something you would be open to?

Apollo docs need to upgrade to the new navbar

The one that lives at https://github.com/apollographql/apollographql.com-nav

[mobile] Can't scroll properly

Swiping up/down middle and middle-left doesn't always work.

Reinstate snippet language

cf #3

offset header on deep link

As a content author,
I want to link to a particular section of a page like https://www.apollographql.com/docs/engine/setup-node.html#enabling-compression ,
So that I can go directly to relevant documentation.

The header bar is in front of the background text, which hides the link anchor and makes the user confused about the link they followed.

Formatting issues for field names/types

See meteor/docs#53

Differentiate code links from code?

They are both green. For instance below, apollo is not a link, but meteorClientConfig is. Maybe make default code text black?

http://dev.apollodata.com/core/meteor.html

Sometimes menu doesn't appear in iOS chrome

Broken line numbers

https://guide.meteor.com/react.html

Don't scroll menu down on version change

before:

after clicking 1.3.2:

Link readibility

This underlining makes it harder for me to read the letters. Maybe no underline or move the line down a little?

<em> is not italic

I have a patch but I'm not sure which branch we should be using. CC @tmeasday - can we get all the sites on one branch of the theme?

Make Guide and API Docs print-friendly

Currently, this is how these sections(Guide and API Docs) appear in Chrome(v52) print-mode(ctrl + p):

I suggest the use of CSS ``@media print` rule in order to:

• hide the navigation and sidebar sections
• remove the left margin from the content section

In code:

@media print {
  .sidebar,
  .nav { 
    display: none; 
  }
  .content {
    margin: 0;
  }
}

After the CSS codes were added:

Commit NOTE:
Because LESS is used, I have split the codes and added them in the appropriate files.

Improve touch menu closing

• open in chrome iOS: http://docs.meteor.com/api/accounts.html#Meteor-userId
• open menu
• try to close menu by swiping from the right side of the screen
• instead, content scrolls horizontally

Make sure forum link goes to same protocol

https://forums.meteor.com/t/http-content-in-meteor-documentation-https-pages/31775

Embed doesn't work on this page: https://guide.meteor.com/routing.html

Because it's trying to point to the http: forum.

Sidebar links no longer highlight in response to content area scroll position

Current behavior
When scrolling the content area the sidebar links no longer highlight via an .active class. This is a regression.

Expected behavior
When scrolling the sidebar links get an .active class. See image:

Code blocks remove empty lines

this code:

becomes:

http://dev.apollodata.com/core/meteor.html#Client

Make snippet line numbers optional?

I'd prefer default off. It feels cluttered to me, and they're usually only useful in cases in which you want to refer to a line number in the surrounding text.

Clicking on anchors adds backslashes before periods

• Go to https://www.apollographql.com/docs/engine/proxy-release-notes.html
• Click on the link icon to the left of the v1.0.4 header
• It properly smooth scrolls to the top
• Look at the URL bar
• See https://www.apollographql.com/docs/engine/proxy-release-notes.html#v1\.0\.4

Where did the backslashes come from? They break links. Note that "copy link address" on the link gets the right error without backslash.

@abernix this might be up your alley?

Versioned documentation without trailing slash breaks links.

This is a problem that only affects the root documentation, but it seems if you go to https://www.apollographql.com/docs/apollo-server/v2 (without the trailing slash), that none of the sidebar links take you to actual pages — instead they 404.

With the trailing slash (https://www.apollographql.com/docs/apollo-server/v2/), everything works properly.

Use Google referrer query parameter to jump to location

Idea from @MichelFloyd – instead of user googling "meteor setpassword" coming the docs accounts page, and then searching setpassword, we automatically, if the Google query was close enough match to something, jump there

Empty lines in code snippets are not displayed