retypeapp / retype Goto Github PK

WARNING: [retype.json] Only edit on GitHub is supported.
         Please use --verbose for more details

Adding edit support for GitLab too

Hi,

Maybe I found a bug in "order option".

Synthèses -> order: 99
Titre -> order: 90
Clauses à modifier -> order: 50
Clauses à ajouter -> order: 49

I think it would be nice to be able to collapse the sidebars on desktop view to keep the UX a little cleaner, and specify in page metadata whether they should be expanded or collapsed upon initial load.

See also

• #629

I have a long and overcomplicated list and the list elements are separated by spaces for the sake of sanity but having spaces between elements causes problems with nested element spacing. Adding spaces between nested elements or removing all spacing fixes it.

## Bee Movie
- According to all known laws of aviation, there is no way a bee should be able to fly.

- Its wings are too small to get its fat little body off the ground.
    - The bee, of course, flies anyway because bees don't care what humans think is impossible.
    - Yellow, black. Yellow, black.

- Yellow, black. Yellow, black.
    - Ooh, black and yellow!

- Let's shake it up a little.

- Barry! Breakfast is ready!

I dunno if this is the expected behavior and I'm just abusing spacing or not.

Retype needs to support all code block reference languages.

Example

```coffeescript
square = (x) -> x * x
cube   = (x) -> square(x) * x
```

```fsharp
// ---------------------------------------------------------------
//         Integers and basic functions
// ---------------------------------------------------------------

module Integers =
    let sampleInteger = 176

    /// Do some arithmetic starting with the first integer
    let sampleInteger2 = (sampleInteger/4 + 5 - 7) * 4

    /// A list of the numbers from 0 to 99
    let sampleNumbers = [ 0 .. 99 ]

    /// A list of all tuples containing all the numbers from 0 to 99 and their squares
    let sampleTableOfSquares = [ for i in 0 .. 99 -> (i, i*i) ]

    // The next line prints a list that includes tuples, using %A for generic printing
    printfn "The table of squares from 0 to 99 is:\n%A" sampleTableOfSquares
```

```objectivec
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[]){

    /* When the @autoreleasepool decorated code block complete,
       all the temporary variables (in the code block) used memory
       will be recycled automatically.*/
    @autoreleasepool{
        // @ means the String is a NSString type string.
        NSLog(@"Hello World Objective-C");
    }
    return 0;
}
```

Hi, a few hours back I got to know about retype and everything about it feels awesome and simple!

It would be really nice if you guys implement full content based search when no matching heading can be found.

Hoping to see this in the future ;)

Thanks!

Hello,

I have a problem when I export. I have a wrong path for resssources.

Example : https://slimooo.github.io/dpo/

Feature Request
Its extremely useful to have namespace level documentation to provide higher level context for the purpose of the classes within a namespace. With previous C# API docs generators, a static NamespaceDoc class could be defined solely to define the comments for a namespace (https://stackoverflow.com/questions/793210/xml-documentation-for-a-namespace).

However though the NamespaceDoc approach is useful, my preference would be a more free flowing markdown solution to introduce a namespace to a reader. This would allow direct editing in markdown rather than editing markdown within a C# comment. The rendered output would have a page for each namespace node in the documentation tree. Currently a namespace has no content in the retype output web UI and is just to open/close a tree node. Potential approaches for namespace markdown include:

• Allow markdown files for namespaces to be defined in the api folder alongside the index.yml file for the API definitions. The convention would be that the markdown file is named after the namespace e.g. System.Collections.Generic.md. Alternatively the namespace could be defined in the metadata section of the markdown file.
• Allow README.md files to be placed in source code folders. The metadata of the README.md file would need to identify which namespace is being documented.
• Just rely on the existing NamespaceDoc.cs convention. Though compatible with other tools, this approach is inconvenient for editing the namespace documentation which is likely to be more descriptive and longer form than the class/member comments.

Hello,

an other bug : https://www.loom.com/share/77c0297529314d34a4b9bd3fe985954a

Only H1 link without french accent (é,è,à) work !

Like almost all documentation staticgen it lacks of tag support.

I explained the idea extensively here: intuit/Ignite#126

I've been trying to use Retype on Windows today, and I run into this error:

For reference, I am running 64-bit Windows 10 Pro.

I have tried uninstalling and reinstalling Retype.

It would be easier to have a tree structure written in navbar.yaml or in the global config file

eg.

nav:
  - Home: index.md
  - Cheatsheet:
    - 'Basic concepts': 'cheatsheet/basic-concepts.md'
    - 'Control structures': 'cheatsheet/control-structures.md'
    - Collections: 'cheatsheet/collections.md'
    - Methods: 'cheatsheet/methods.md'
    - 'Object oriented programming': 'cheatsheet/object-oriented-programming.md'
    - 'Modules, mixins and standard classes': 'cheatsheet/modules-mixins-standard-classes.md'
    - Files: 'cheatsheet/files.md'
  - About: 'about.md'

rather than having to play with the order meta-data in all files.

Originally posted by @slimooo in #18

See also

• #235
• #18

1. How to replace the word "filter" in the search with another?
2. Where to edit styles?
3. Will it be possible to run your ssg on such hosting as netlify, vercel, hostman, render.com etc? (i mean the build process. For example, for react and docsify this works, but for retype it does not)

It would be nice to have an author section built into the page metadata so that readers can view who wrote that specific "article."

The right sidebar shows / highlights the wrong current title level

eg. https://retype.com/configuration/project/#colors

Version: v1.6

See also

• #134

Two or more multiple levels dropdown menus in retypes.json - links:

Discussed in #84

Hi, this is a bug report.

Please check these links to understand what's wrong:

• https://wiki.supreme-gamers.com/common-issues/gathering-logs/#from-windows
• https://wiki.supreme-gamers.com/common-issues/gathering-logs/#from-linux

If I unwrap the panel component then everything is okay.

Thanks.

I have two independent retypeapp generated web locations. Each have a link to the other in their retype.json links section. Clicking on those links switches the main content pane (centre) and the content menu pane (right) correctly. However, the page hierarchy (left) does not get updated. It keeps the page hierarchy for the first retypeapp web location that was loaded.

Would a generated site benefit from SEO by adding these two files?

Hi again.
It would be nice if we could click on images, plus the ability to zoom into them over a simple lightbox.
Thanks.

See also

• #25

Retype uses Markdig as the primary Markdown parser. As per the Markdig LICENSE, the copyright notice and other statements are to be available in the documentation.

We can add some other learning resources on how Retype is integrating Markdig and how awesome Markdig is.

Copyright (c) 2018-2019, Alexandre Mutel
All rights reserved.

Redistribution and use in source and binary forms, with or without modification
, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this 
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, 
   this list of conditions and the following disclaimer in the documentation 
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Hi, I want to submit a feature request, it would be good if the images can view on the carousel (or slider) layout.

Thanks.

Marvin Jung

See also

• #61
• #186

I think that a useful feature, especially if Retype is being used in a setting where content needs to be edited continuously, would be for the end-user to be able to add articles and edit existing articles from the website itself. With that being said, are there plans for ways to authenticate users, thus limiting access to who can access the site?

Hello, this is another feature request of mine.
I think it would be great if this is implemented in retype.
Or more like there should be a retype component which would allow us to do so.
Thanks!

Hey there! I've noticed that there is no way for a user to remove the "next" and "back" buttons on the bottom of each page, for specific pages. Having these buttons for specific pages, such as landing pages, is especially pointless. In my opinion, having it as an option in the metadata section for each page would be a good implementation.

I can not deploy to vercel hosting

The icon component documentation refers to an octicon search page which includes icon names which retypeapp does not support.

For example, the person-add icon results in the following warning:

WARNING: [file.md:line] Unexpected Octicon icon "person-add".

It is preferable that retypeapp supports the icon names defined in the latest version of the octicon content (or at least the latest version at the time of the retypeapp release).

Its likely that support for C# documentation comments is already planned in future versions. The following link summarizes the comment syntax:
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

Even if the document comment support is planned, can the following be considered in its development:

• Ensure that support for markdown within the C# comments is retained. This is too valuable to lose.
• As early as possible in the beta versions, generate at least the unmodified text of C# comment syntax in the output. It will be ugly but at least the full comment is generated in beta versions. Currently the comment html generated wipes out some (all?) comment syntax in angle brackets.

You wrote a Github Actions + Github pages deploy page. I'd like to PR one for Gitlab CI + Gitlab Pages.

A simple naive CI gitlab-ci.yml:

image: node:lts-alpine

before_script:
  - npm install --global retypeapp # https://retype.com/guides/getting-started/

pages:
  script:
  - retype build
  - mv site public
  artifacts:
    paths:
    - public
  only:
  - master

I'll PR when I'll have fixed this error:

$ retype build
events.js:352
      throw er; // Unhandled 'error' event
      ^
Error: spawn /usr/local/lib/node_modules/retypeapp/platforms/linux-x64/retype ENOENT
    at Process.ChildProcess._handle.onexit (internal/child_process.js:269:19)
    at onErrorNT (internal/child_process.js:467:16)
    at processTicksAndRejections (internal/process/task_queues.js:82:21)
Emitted 'error' event on ChildProcess instance at:
    at Process.ChildProcess._handle.onexit (internal/child_process.js:275:12)
    at onErrorNT (internal/child_process.js:467:16)
    at processTicksAndRejections (internal/process/task_queues.js:82:21) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'spawn /usr/local/lib/node_modules/retypeapp/platforms/linux-x64/retype',
  path: '/usr/local/lib/node_modules/retypeapp/platforms/linux-x64/retype',
  spawnargs: [ 'build' ]
}

Incremental build can be helpful when used with the retype watch command.

The process rebuilds changed pages only as well as dependent app parts:

• search.json
• config.js (sidebar items)
• pages referring the changed ones (in order to resolve/validate links)

In order to get this working, the incremental build process should maintain/cache some data required to help generate the items listed above without re-parsing the source .md files.

Sometimes an author may want to edit the retype markdown content without needing to view the API documentation. Currently running retype watch when there is significant API content will be quite slow to start up because it has to generate the API content.

Possible improvements to retype watch include:
Either: Don't generate the API content unless --api is specified.|
Or: Add another option --dont-generate-api

Hello.
This is another feature request I would like to make 😃
Thanks!

https://mermaid-js.github.io/mermaid

<div class="mermaid">
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</div>

See also

• Discussion #31 (@ApolonTorq)

Is there a way I can see what's possible with the site layout/theme/styles without downloading and trying the project out for myself? Maybe some examples or something. Thank you!

Hello,

First of all, I am very excited about this tool. It looks very polished and lightweight, and very easy to use.

I noticed that the watch and run command only allow setting the --port but not the bind address, and it listens on localhost. In some scenarios - like mine, when using Vagrant - there is a need to listen on 0.0.0.0 instead.

Is there a plan on adding such option?

Hey again! One feature I'd really like to see is the ability to remove folders from the front-end hierarchy. The current way is something like this:

|-- /folder
    |-- /folder2
        |-- sample.md

It will also show that way on the deployment as well. While that is useful, that method quickly falls apart when you attempt to organize files and images into folders. Say in a folder, you have this structure:

|-- /Example
    |-- /ExampleFolder
        |-- sample.md
        |-- image.png
    |-- /ExampleFolder2
        |-- sample2.md
        |-- image.png

When viewing the website, it will create two subfolders in the Example folder, ExampleFolder and ExampleFolder2. This creates unneeded levels within the site. There could be an option in the configuration in each Markdown file to ignore the immediate folder hierarchy and to serve it directly under the parent folder (hopefully that made sense).

Hi, this is a bug report.
Assume my site is example.com with a file hierarchy of:

docs
|-- hello.md
|-- Music-One.mp3

README.md

Now if I use the following markdown code in docs/hello.md:

[!file Music](Music-One.mp3)

It will result in example.com/docs/hello/music-one.mp3 for the html output.
While it should have been example.com/docs/Music-One.mp3 as Music-One.mp3 file resides under docs dir and not docs/hello non-existent dir.

Also notice that the file name Music-One.mp3 got lowercase and did not remain case-sensitive for the HTML output, thus resulting in unexpected behavior.

I would also suggest to use the HTML download tag for prompting browsers to perform download for unrecognized downloadable file types.
Here is an example for such a type: https://raw.githubusercontent.com/supremegamers/wiki/main/common-issues/DarkMatter-Exo4.7.cfg

Thanks.

Hello,

It's possible to generate automaticly a sitemap or a rss feed ?

Thank you

Hi, this is a bug report.
Basically I think retype should better scale the title-bar element for mobile devices.
Please see the video below to better understand the issue:
https://user-images.githubusercontent.com/39482679/124686799-8da9c780-def5-11eb-9a82-bdfbbcce748b.mp4
If you can't play the video then see on streamable: https://streamable.com/jd82sf

Also on checking from emulated mobile view on firefox, I find that devices with width below 386 causes raw links in the page to be overflowed from the main body. Here is an example below:

Although it's fine over 386 width relative to the longest link:

Thanks

Retype needs to allow the custom configuration of the port used by the internal webserver during retype watch or retype run.

Default is 5000.

{
    "port": 5001
}

Thank you for this beautiful docs project, I really love it😍.

My current issue is I want to display both title and logo together on the docs, but it is not displayed when logo or logoDark is configured according to (https://retype.com/configuration/project/#title).

My proposed solution

{
  "branding": {
    "title": "Example.com",
    "logo": "static/logo.png",
    "hideTitle": false
  }
}

Thank you.

Reposted here as a feature or enhancement request.

Discussed in #57

Right now (v1.6) only label color can be changed, I guess it's planned to make the global accent color changeable (used by links for example).

  "branding": {
    "title": "Ruby Cheatsheet",
    "label": "Docs",
    "colors": {
      "label": {
        "text": "#cc342d",
        "background": "#f1c3c0"
      }
    }
  },

I've observed the following:

• The contents section in the right hand column of the retypeapp UI lists headings in a hierarchical manner with indents to present the hierarchy.
• The contents section does not display heading-1 # entries. It only displays heading-2 ## and higher entries.

If these observations are correct then it does not make sense to have more than the single heading-1 # entry at the top of the page. If a user defines multiple heading-1 # sections in the page, the contents will not include those headings making it more difficult to navigate in the page.

Feature Request:
Issuing a warning when multiple heading-1 # sections are used alerts users to the content section behavior and should prompt them to restructure to use heading-2 and higher sections. This is worth doing even if this issue is highlighted in markdown editor of choice. It makes it clear that retype is not showing that heading in the contents list.

Hello,

Can you please add the possibility to add easily videos (youtube, dailymotion...), music (soundcloud, deezer...), codes (codepens...) ?

Thank you :)

Discussed in #72

Retype uses Scriban as the primary template parser. As per the Scriban LICENSE, the copyright notice and other statements are to be available in the documentation.

Copyright (c) 2016-2020, Alexandre Mutel
All rights reserved.

Redistribution and use in source and binary forms, with or without modification
, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this 
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, 
   this list of conditions and the following disclaimer in the documentation 
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.