bep / docuapi Goto Github PK

Hi,
similarly to the languages (in fact, in addition to the languages), it would be cool to have the versioning of the documentation. Any ideas on how to enable this ?

The theme fail when a baseURL contains a path.

Works:

baseURL = "https://mydomain.com/"

Doesn't works:

baseURL = "https://mydomain.com/content/"

Configuration:

baseURL = "https://mydomain.com/content/"
languageCode = "en-us"
title = "test"
theme = "github.com/bep/docuapi"

disableKinds = ["taxonomyTerm"]

# Code higlighting settings
pygmentsCodefences = true
pygmentsCodeFencesGuesSsyntax = false
pygmentsOptions = ""
pygmentsStyle = "monokai"
pygmentsUseClasses = false

[params]
  search = true

Logs:

ERROR 2019/08/15 19:17:56 Lib not found: "//= require ./all_nosearch"
ERROR 2019/08/15 19:17:56 Lib not found: "//= require ./app/_search"
ERROR 2019/08/15 19:17:56 Lib not found: "//= require ./lib/_energize"
ERROR 2019/08/15 19:17:56 Lib not found: "//= require ./app/_toc"
ERROR 2019/08/15 19:17:56 Lib not found: "//= require ./app/_lang"
Total in 1149 ms
Error: Error building site: failed to render pages: render of "home" failed: execute of template failed: template: _default/list.html:9:7: executing "_default/list.html" at <partial "js.html" .>: error calling partial: "/tmp/hugo_cache/modules/filecache/modules/pkg/mod/github.com/bep/[email protected]/layouts/partials/js.html:10:33": execute of template failed: template: partials/js.html:5:13: executing "partials/js.html" at <partialCached "funcs/get_and_concat.html" (dict "imports" $importsAll "target" "js/all.js") "all">: error calling partialCached: "/tmp/hugo_cache/modules/filecache/modules/pkg/mod/github.com/bep/[email protected]/layouts/partials/funcs/get_and_concat.html:10:33": execute of template failed: template: partials/funcs/get_and_concat.html:10:33: executing "partials/funcs/get_and_concat.html" at <resources.Concat>: error calling Concat: slice []interface {} not supported in concat

I do the command

hugo server -t docuapi

and it installs some modules and then apparently tries to install the modeul for 'slatedocs/slate' but then fails with this erro

`Error: module "github.com/slatedocs/slate" not found; either add it as a Hugo Module or store it in "/Users/yangnom/www/quickstart/themes".: module does not exist'

I'm guessing because that reference doesn't exist anymore, but maybe I'm just dumb and doing something wrong...

Is it possible to have highlighted code in the left section of the site? Some way of preventing Hugo from moving it to the "code area" on the right side.

If there is no way already, I might dig into Hugo and this template and submit a PR.

Hi,

I am a bit confused as to how the TOC rendering works.
Should not all headings be rendered to TOC up to depth maxMenuDepth?

Here are some examples.

my config.toml has

maxMenuDepth = 3

Example 1:

---
weight: 10
title: Test
---

# h-1 

## h-1-1

Renders (only showing relevant bits of html)

<li>h-1</li>

Example 2:

---
weight: 10
title: Test
---

# h-1 

## h-1-1

### h-1-1-1

Renders

<li>h-1</li>

Example 3.

---
weight: 10
title: Test
---

# h-1 

## h-1-1

### h-1-1-1

## h-1-2

Renders

<li>
    h-1
    <ul>
        <li>
            h-1-1
            <ul>
                <li>
                    h-1-1-1
                </li>
            </ul>
        </li>
    </ul>
</li>

Or, am I misunderstanding the feature...

It looks to me as if level 2 is not rendered in all cases.

Same applies if I set

maxMenuDepth = 2

By the way, thanks for the great theme!

Tried to do it, but seems they have done some CSS changes that also needs some adjustments on this sidse.

Linking screenshots in the README with relative paths might work on GitHub, but the theme site can't find the screenshot under this path. Consider to use an absolute one instead.

Btw, you did a great job with this theme 👍

This issue is to ask two questions about titles in this theme.

On the one hand, title fields in the front-matter of markdown files in content seem to be ignored. I removed them and I found no difference in the output. If this is the expected behaviour, I'd ask to consider changing it so that title fields are used as # headings. Naturally, this would imply removing explicit # headings, to avoid duplication.

On the other hand, I didn't find how to add headings which are not included in the TOC (sidebar). I could use <h1>Title</h1> instead of # Title. However, doing so breaks the dynamic behaviour of the sidebar: level 1 items are shown only, none of them is expanded/collapsed.

Hence, I think that these two questions might be tightly related, since applying the former would probably break the sidebar.

Seems notes and warnings from slate syntax is not working, also as in the example site.

Can you help to have a look.

Not sure whether related to specific version, currenly with go1.13.6, hugo version 0.73.0 and the latest of docuapi.

Not sure what the problem is, but when generating the site with hugo, it only creates the pages for index.md and not errors.md.

I would like to control the generated hash, so that I can link between pages and safely update page titles.

e.g. main.md

----
weight: 17
title: hello world
hash: "hello"
---

# hello world

expected resullt http://localhost:1313/#hello
current result: http://localhost:1313/#hello-world

I'm a Hugo noob, so please execuse if I'm missing something obvious.

According to https://github.com/bep/docuapi#hooks:

When the fix for #2549 is released we may do this with blocks

The issue seems to be fixed/released some months ago. Is the description in the README still valid or is this theme to be updated/modified yet?

Hi,

I really like this theme and was thinking about adding a favicon. Is it possible in this version?

Thx

First thanks for your work: It's really amazing

Except if I missed something but I can't find your javascript source code...
So it's impossible to change / fix anything. I think that providing minify version of javascript is fine, but can you also push on Github all source file ?

It will able anyone to fix javascript issue if any.

Using backslashes in a code block with a sh command, produces coloured symbols that are wrapped in <span>. As a result, additional space is shown. For example:

docker run --rm \
  -v //var/run/docker.sock://var/run/docker.sock \
  -v issues://volume \
  eine/issue-runner <ref>

if using github pages in a repo, the non-relative paths "" are broken - because they are really located at /reponame/slate/etc

I've an error on hugo server:

Building sites … Total in 6 ms
Error: Error building site: failed to render pages: render of "home" failed: 
"~\docuapi\layouts\_default\list.html:3:62": execute of template failed: template: _default\list.html:8:7: 
executing "_default\\list.html" at <partial "styles.html" .>: error calling partial: 
"~\docuapi\layouts\partials\styles.html:3:62": execute of template failed: template: partials/styles.html:3:62: 
executing "partials/styles.html" at <toCSS $cssOpts>: error calling toCSS: type map[string]interface {} not supported in Resource transformations

I had correct building site with hugo server about one month ago. And i did some customization on my own docuapi successfully . every things were ok. But after 1 month i came back to add new changes and i encountered to this error.

Could you help me for resolving this problem?

Hi guys,
may be this is a stupid question but I can't start using this theme because when I start server from command line the answer is:

"Module "LoveIt" not found; either add it as a Hugo Module or store it in "/Users/antedoro".: module does not exist".

Hugo version: v0.74.3/extended

Thi is steps I made:

1. hugo new site myLoveItSite
2. cd myLoveItSite
3. git clone https://github.com/dillonzq/LoveIt.git themes/LoveIt
4. hugo server -D

It's the same answer when I copy exampleSite folder contents in root folder.

Can you take me some advice?

Works fine on my MacBook (both Firefox and Chrome).

• the theme colors are not the same
• the menu are always expended and cannot be collapsed
• some icons are missing (ex: search, note)

Is it expected?

Before:

After:

I am having trouble with manual alignment of code blocks (blockquote and pre selectors). I simply need the vertical alignment of code blocks to match h2 headers in my markdown. Out of the box, the code blocks appear anywhere from 71 to 400 pixels below the text headers on the left. This misalignment is what I need to change.

I've tried to do this manually by adjusting the blockquote and pre margin-top values, but this is inconsistent depending on resolution/layout. I tried adding selectors to the partial layout file but it had no effect.

I also looked upstream for a solution but the only thing I could find involved adjusting the layout.erb file which is N/A in the docuapi port. Here is someone asking the same question there.

Does anyone have suggestions?

I want to use code block inline in middle column instead of right one and I do not need right column for syntax highlighting. Can it be switched off ?

Currently the maximum supported depth for rendering ToC is 2 (basically h1 and h2). I was about to enhance this and send a PR but decided to start the discussion first.

• was this intentional? or hasn't been done simply because of lack of interest or request of the feature?
• I was going to enable up to 3 levels depth (h1, h2 and h3). If we're going to consider this enhancement, what the maximum depth should be? In my use case 3 is enough (and I can argue in general it would be).

Any thoughts, comments or suggestions on the matter?

When language of the doc is switched to other languages like Chinese, or Norwegian like in the example site, the h2 items in TOC can not be expanded or collapsed automatically while scrolling the doc page, or being displayed when clicking on any h1 items with children.

Is there any way to make it work in other languages?

http://docuapi.com/

Hey @bep so cool to find this theme to test out. I'm stumped that when I reduce the page width to simulate a mobile device, the code language selector disappears. I think the ideal experience would be to paste it above each code block section (and display only the available languages). Just a thought for discussion. Thanks!

Hei guys, can you please have a very short installation guide to get this up?
Thanks.

I have a trivial bug in that any inline code (i.e. something like this) is getting cutoff (like justified alignment). If I make the same text bold, it remains in-tact, but inline code gets chopped, and the remainder ends up on the next line.

Any suggestions on how I can tweak the CSS to avoid that?

Thanks for creating this useful theme!

I have a question that might be a limitation of Slatedocs itself.

I'd like to be able to define tabs that show several languages.

For instance, for documenting a web API that has an R client providing parsed output

• A tab with R code and R output
• A tab with shell commands and JSON/XML output.

My workaround is to define the second tab for "JavaScript" because highlighting shell/JSON/XML as if it were JavaScript does not look too horrible.

Any insight on how to tweak this theme to be able to use something like

[[params.language_tabs]]
  key = "r"
  name = "R" 
[[params.language_tabs]]
  key = "shell"
  name = "Shell"
  otherlangs = ["json", "xml"] 

is welcome. 🙂 I guess I'd need to tinker with https://github.com/bep/docuapi/blob/master/assets/js/slate/app/_lang.js and

In the README it's read that:

If you want a different page selection, please provide your own layouts/index.html template.

However, there is no layouts/index.html file in the theme. The logic seems to be defined in layouts/_default/baseof.html. Is the comment correct or is it outdated?

Currently if I write a heading such as:

Step 1 - Setup

Then it generates an anchor URL for this header like the following:
example.com/api/#step-1---setup

That step-1---setup just looks horrible in the URL.
Is there a way to customize it right in the markdown where we specify the heading?
Something like:

Step 1 - Setup <a=setup>

Gracias!

Hi, great work!

Would you add a feature to let user change panels width (or hide them)?

I just copied repository and deploy it to netlify. So deployment goes from exampleSite folder. How do I change favicon? I tried many ways, such as:

1. Adding favicon.ico in "static" folder that is located in the root directory.

2. Adding favicon.ico in "static/images" folder that is located in the root directory and creating head.html file in "layouts/partials" folder that is located in the root directory and put there <link rel="icon" href="{{ "images/favicon.ico" | relURL }}">

3. Adding favicon.ico in "static/images" folder that is located in the exampleSite directory and creating head.html file in "layouts/partials" folder that is located in the exampleSite directory and put there <link rel="icon" href="{{ "images/favicon.ico" | relURL }}">

Also I tried different href values, like href="images/favicon.ico", href="{{ relURL "images/favicon.ico" }}"

Nothing works.

Issue: When visiting (or refreshing) a DocuAPI website, all lang codes are displayed. A user have to click any language at the top bar to filter it out.

Tested on:

• Demo site: https://docuapi.netlify.app/
• SemWeb docs: https://semweb.youronly.one

DocuAPI version:

• Demo site: not sure but I'm assuming it's v2.0.1
• SemWeb docs: v2.0.1 as per go.mod file and module.toml

go.mod

github.com/bep/docuapi v1.5.2
github.com/bep/docuapi/v2 v2.0.1

module.toml

[[imports]]
  path = "github.com/bep/docuapi/v2"

Platform: Ubuntu 20.04 LTS

Browsers:

• Firefox 95.0b7 (dev channel)
• Edge 97.0.1069.0 (dev channel)

Hugo version: v0.89.3

Shalom!

Hello! I try to apply theme for multiply independent pages of documentation, but i can't find a way how to do it, can you provide i little example please?

When i create file inside content folder, everything is OK. But when i try to add directories, so i could have 2 different pages, i get empty pages rendered...

I mean, when i create 2 sub-dirs (/content/first/, /content/second/) I want to see 2 different pages
http://localhost:1313/first
http://localhost:1313/second

Is that possible?

I would like to be able to use just one tab so that I don't have to switch between the tabs while doing some documentation for self and the team.

I’ve inherited a Hugo project at work that uses the DocuAPI theme. I want to update it, but I don’t know how and I can’t find any instructions on either the Hugo documentation or in this repository on how to do it.

So, how does one install or update this theme?

In the project, I find a themes/DocuAPI directory that looks like it is a different (read: much older) version of the same files contained within this repository at the root level (i.e. there are archetypes and assets directories, etc.). However, just downloading a copy of this repository’s contents and replacing the directory in the project just breaks the project build (with Error: module "github.com/slatedocs/slate" not found; either add it as a Hugo Module or store it in "/src/themes".: module does not exist) and it’s not clear what the issue really is. It sounds like a dependency issue, but since there are no instructions on how to install dependencies, I turn in circles.

Furthermore, I can’t find any information as to which version of the theme I’m using in the project right now. That prevents me from looking at the release log and updating in small steps in order to take care of any breaking changes that might’ve happened along the way.

I'm trying to add the Module hugo-mod-bootstrap-scss-v4 but the bootstrap code is not mounted being mounted at assets/scss/bootstrap.

Thanks for this great theme @bep

Two different .md files with different weights and content but the same heading are randomly allocated with the same row.id causing both of them to open their sub-menus simultaneously while scrolling. Please take a look at the photo below.

They both have the address - http://localhost:1313/#query-parameters-10

I've cleared the cache. I tried publishing to the online site - the issue remains.

Very difficult theme to understand. I created new project with "hugo new site ...". Then I created folder "docuapi" inside "themes" folder and put there files from THIS github. Then I tried to launch project with "hugo server" command. It didn't work.
Then I took this configuration https://github.com/bep/docuapi/blob/master/exampleSite/config.toml which YOU provide. I put it in "config.toml" file in main directory and it STILL doesn't work.
How do I make it work?

I'm sorry this is not an actual issue and just a question but I couldn't find another way to ask.

I'm trying to understand how does this project incorporate slate, but all I found was slate's styling.
My current understanding is that this theme only uses slate's styling and the rest is from this project, even if that's correct I still would like to know how does this theme obtain the styling, is it copied, is it generated in some way?

Hi,
How can i add images in the document?
can you help me?

thanks.

https://github.com/pressly/chi

Hi @bep, The page content on the left seems to move when I move through the code examples tab. Each tab takes it to a different part of the section, so the section I am supposed to be on isn't the case anymore. I made a video of how "Slate" works and how "docuapi" seems not to work similarly to clarify this point.

Slate (How it is supposed to work as you switch different code blocks)
https://user-images.githubusercontent.com/20136098/233024178-d494ee28-5ce8-441f-a5ec-405f3ee8880e.mp4

Docuapi (How it is currently working)
https://user-images.githubusercontent.com/20136098/233023639-4c5aa1ed-c182-4685-8f77-328ffc362859.mp4

Probably fix it in the theme gen script.