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

Support Version/Language dropdown menu & custom CSS/JS support #150

Open
wants to merge 4 commits into
base: release
Choose a base branch
from

Conversation

life1347
Copy link

@life1347 life1347 commented Jan 8, 2024

Changes

Please describe the changes made in the pull request here.

This PR aims to add useful features, include

  • Version dropdown menu
    • This implementation redirects user to any URL user specific, for example https://v0-2.lotusdocs.dev/, and user is responsible to add new DNS and hosting a site for out-of-date docs.
  • Version warning banner
  • Multilingual mode & dropdown menu
  • Custom JS/CSS

Version dropdown menu

Screenshot 2024-01-08 at 12 54 52 PM

Multilingual mode

Screenshot 2024-01-08 at 12 54 56 PM

Banner for archived doc

Screenshot 2024-01-08 at 12 55 26 PM

Banner for unreleased doc

Screenshot 2024-01-08 at 12 55 50 PM

To enable these features, following config must be add to hugo.toml

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true

[languages]
  [languages.en]
    contentDir = 'content/en'
    disabled = false
    languageCode = 'en-US'
    languageDirection = 'ltr'
    languageName = 'English'
    title = 'Project Documentation'
    weight = 2
    [languages.en.params]
      subtitle = 'Reference, Tutorials, and Explanations'

  [languages.zh-hant]
    contentDir = 'content/zh-hant'
    disabled = false
    languageCode = 'zh-Hant'
    languageDirection = 'ltr'
    languageName = '正體中文'
    title = 'Project Documentation'
    weight = 2
    [languages.zh-hant.params]
      subtitle = 'Reference, Tutorials, and Explanations'

[params]

  # CSS/JS for home page
  customCss = [] 
  customJs = []

  # CSS/JS for doc pages
  docCustomCss = ["css/custom.css"]
  docCustomJs = []

[params.versionInfo]
  dropdownMenuText = "Releases"
  archived = false                     # indicate this is an archived doc set branch and display warning banner - default false
  unreleased = true                   # indicate this is an unreleased doc set branch and display warning banner - default false

[[params.versions]]
  version = "Nightly"
  url = "https://nightly.lotusdocs.dev/"

[[params.versions]]
  version = "v0.1.0"
  current = true                       # display as current branch version

[[params.versions]]
  version = "v0.0.0"
  url = "https://v0-1.lotusdocs.dev/"

For Multilingual, language specific documentation must be placed in the content/<lang>/docs, like the following

Screenshot 2024-01-08 at 12 59 12 PM

To add custom CSS/JS, you must place files under static/css & static/js. For example, I add custom.css and the hugo.toml I've used is

  docCustomCss = ["css/custom.css"]
  docCustomJs = []

Below you'll find a checklist. For each item on the list, check one option and delete the other.

Dark mode

  • [ V ] The UI has been tested both in dark and light mode
  • [ X ] This PR does not change the UI

Copy link

netlify bot commented Jan 8, 2024

👷 Deploy request for hugo-lotusdocs pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit ebd922d

</span></div>

<div class="w-100">
<p>Version <strong>{{ $currentVersion | markdownify }}</strong> documentation is <strong>unreleased and frequently changed</strong>. For up-to-date information, see the <a href="{{ $latestVersionUrl | safeURL }}" target="_blank"><strong>latest version</strong></a>.</p>

Check warning

Code scanning / CodeQL

Potentially unsafe external link Medium documentation

External links without noopener/noreferrer are a potential security risk.
</span></div>

<div class="w-100">
<p>Version <strong>{{ $currentVersion | markdownify }}</strong> documentation is <strong>no longer actively maintained</strong>. The version you are currently viewing is an archived snapshot. For up-to-date information, see the <a href="{{ $latestVersionUrl | safeURL }}" target="_blank"><strong>latest version</strong></a>.</p>

Check warning

Code scanning / CodeQL

Potentially unsafe external link Medium documentation

External links without noopener/noreferrer are a potential security risk.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant