facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
56.85k stars 8.56k forks source link

Autogenerated versions.js page does not link back to versioned docs #1166

Closed amimas closed 5 years ago

amimas commented 5 years ago

šŸ› Bug Report

The /versions page shows a list of versions, but "Documentation" and "Release Notes" links are not working. On the browser, they are linking back to the same page (/versions).

Also, the documentation does not have any reference to where "Release Notes" are stored. Are they expected to be a tag in Github or can we have an actual doc published elsewhere or another static page/doc within docusaurus.

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

  1. Run the following script to generate a starter versions page listing all the site versions: yarn examples versions
  2. This creates the pages/en/versions.js file.
  3. Run the script with a command line argument of the version you wish to create. e.g.: yarn run version 1.0.0
  4. Start the server: yarn start
  5. Visit the site on your local host: http://localhost:3000/en/versions
  6. Try the "Documentation" and "Release Notes" link

Expected behavior

Clicking on the "Documentation" link would take me to the pages that are created when clicking on the Docs link from the top navigation bar.

Not sure what to expect from the "Release Notes" link because I can't find any related configurations in previous steps or in siteConfig.js

Actual Behavior

Neither links (Documentation, Release Notes) are valid. They refer to the same page (/versions). I did notice that the generated /pages/en/versions.js file contains empty href attribute. Am I expected to manually fill-in this information? If yes, that is okay with me, but I didn't see it mentioned anywhere in the docs.

<h3 id="latest">Current version (Stable)</h3>
          <table className="versions">
            <tbody>
              <tr>
                <th>{latestVersion}</th>
                <td>
                  <a href="">Documentation</a>
                </td>
                <td>
                  <a href="">Release Notes</a>
                </td>
              </tr>
            </tbody>
          </table>

Reproducible Demo

(Paste the link to an example repo, including a siteConfig.js, and exact instructions to reproduce the issue.)

I'm sorry I don't have an example repo to share with you as I'm working with an internal/private repo. Here's a copy of the siteConfig.js. I followed the steps in the docs to prepare the site.

/**
 * Copyright (c) 2017-present, Facebook, Inc.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

// See https://docusaurus.io/docs/site-config for all the possible
// site configuration options.

// List of projects/orgs using your project for the users page.
const users = [
  // You will need to prepend the image path with your baseUrl
  // if it is not '/', like: '/test-site/img/docusaurus.svg'.
  {
    caption: 'Garmin',
    image: '/img/customers/garmin_logo.png',
    infoLink: 'https://www.garmin.com/en-CA',
    pinned: true,
  },
  {
    caption: 'Herschel',
    image: '/img/customers/herschel-logo.png',
    infoLink: 'http://www.herschelsupply.ca/',
    pinned: true,
  }
];

const siteConfig = {
  title: 'Developer Center', // Title for your website.
  tagline: 'Documentation for Elastic Path Commerce',
  url: 'https://your-docusaurus-test-site.com', // Your website URL
  baseUrl: '/', // Base URL for your project */
  // For github.io type URLs, you would set the url and baseUrl like:
  //   url: 'https://facebook.github.io',
  //   baseUrl: '/test-site/',

  // Used for publishing and more
  projectName: 'test-site',
  organizationName: 'ep',
  // For top-level user or org sites, the organization is still the same.
  // e.g., for the https://JoelMarcey.github.io site, it would be set like...
  //   organizationName: 'JoelMarcey'

  // For no header links in the top nav bar -> headerLinks: [],
  headerLinks: [
    {doc: 'setup/index', label: 'Docs'},
    {doc: 'ref-exp-vestri/overview', label: 'Reference Experience'},
    {page: 'help', label: 'Help'},
    // {blog: false},
    // {search: true},
    //link to elastic path home page
    // { href: 'https://www.elasticpath.com/', label: 'Elastic Path'},
    //link to elastic path gitlab
    // { href: 'https://code.elasticpath.com/', label: 'GitLab' },
  ],

  // If you have users set above, you add it here:
  //users,

  /* path to images for header/footer */
  headerIcon: 'img/elastic-path-logo.svg',
  footerIcon: 'img/elastic-path-logo.svg',
  favicon: 'img/favicon/ep.ico',

  /* Colors for website */
  colors: {
    primaryColor: '#00A3DD', //'#2E8555',
    secondaryColor: '#0718c2', //'#205C3B',
  },

  /* Custom fonts for website */
  /*
  fonts: {
    myFont: [
      "Times New Roman",
      "Serif"
    ],
    myOtherFont: [
      "-apple-system",
      "system-ui"
    ]
  },
  */

  // This copyright info is used in /core/Footer.js and blog RSS/Atom feeds.
  copyright: `Copyright Ā© ${new Date().getFullYear()} Elastic Path`,

  highlight: {
    // Highlight.js theme to use for syntax highlighting in code blocks.
    theme: 'default',
  },

  // Add custom scripts here that would be placed in <script> tags.
  scripts: ['https://buttons.github.io/buttons.js'],

  // On page navigation for the current documentation page.
  onPageNav: 'separate',
  // No .html extensions for paths.
  cleanUrl: true,

  // Open Graph and Twitter card images.
  ogImage: 'img/elastic-path-logo-RGB.svg',
  twitterImage: 'img/docusaurus.png',

  // Show documentation's last contributor's name.
  // enableUpdateBy: true,

  // Show documentation's last update time.
  enableUpdateTime: true,

  // Show a button at the bottom to scroll to the top
  scrollToTop: true,

  // You may provide arbitrary config keys to be used as needed by your
  // template. For example, if you need your repo's URL...
  //   repoUrl: 'https://github.com/facebook/test-site',
};

module.exports = siteConfig;
derekflint commented 5 years ago

@amimas I fixed myself although it seems this behavior should be auto generated with version creation.

Inside version.js I added:

const versionMap = {}; versions.map(version => versionMap[version] = docs/${version}/doc.html);

Then for url i added:

href={versionMap[version]}>Documentation