Update to documentation.

[OdifYltsaeb]

I'm trying to get my first project outstatic/nextjs off the ground and I'm running headfirst into missing documentation issues. Without whining, I'll outline them here:

• The first startup page image (this one: https://outstatic.com/docs/images/outstatic-welcome-U1ND.png) says that OST_REPO_SLUG is missing, yet it does not explain what should be the value for it. Also you mention that OST_REPO_OWNER is "optional" which makes me think that that the slug should invude username (OdifYltsaeb in my case) . Yet when you set it to OdifYltsaeb/repo_name and set OST_REPO_OWNER to OdifYltsaeb, then the application will complain, that the repo slug should not contain the username. TODO: Please provide a clear example of what is the repo slug. Clarify right away, that username should not be a part of the repo slug.
• At no point is it clarified what kind of repo it should be. Should it be a new and empty repo just for content? Should it be the same repo where the rest of the project will be? Can I keep the content separated from the rest of the application?

I think I should put the following to issues/bugs instead. But maybe I'm missing something, and they are not bugs at all, but rather something I could fix/solve with better documentation. This is why I file this request under update to documentation.

• My project runs at 127.0.0.1:8000 locally. This is what my /outstatic page looks like:
  
  None of the requests are 404 so I'm not sure what is missing, but you can see that it's broken. No idea why. The other pages work just fine.
• I'm note able to create a new collection. It fails with this error: Oops! We couldn't create your collection. Please, make sure your settings are correct by clicking here .
• Once I go to settings page I am unable to actually change anything there. My main branch is "master" yet the settings page says this:
  

Other documentation that could be improved upon:

• Environment variables:
• OST_CONTENT_PATH - # Where content is saved. Defaults to outstatic/content if empty. - What is kind of path is this outstatic/content? Local folder? which is the parent? Where?
• OST_MONOREPO_PATH - # Specify monorepo folder of your Outstatic content. What do you mean monorepo folder? What is that path there? What is monorepo on your sense? Does it mean that If I have nextjs project with outstatic I now have a monorepo since it hosts 2 projects?

In any case, I've not been able to get the project up and running, and I need help. Or please provide clearer and better examples in your documentation. If you manage to help me I'll come up with suggested documentation changes that would have prevented this post being ever posted.

[avitorio]

Hey @OdifYltsaeb,

Sorry to hear you're having trouble with your setup.
I've updated the documentation to give more explicit info on the env vars.

The screenshot you shared seems to be a problem with css not being loaded. Did you create your layout.tsx in the order and with the contents specified in the docs?

You shouldn't need the OST_CONTENT_PATH nor the OST_MONOREPO_PATH for your project. They are optional.

And lastly, what version of Next.js are you using? We currently don't support version 15 yet.

If you need more support, here's a link with some of the support options.

I hope this helps.

[OdifYltsaeb]

hey @avitorio , Thank you for responding!

• My nextjs version is 14.2.14,
• I created layout.tsx following this page/guide 1 to 1 https://outstatic.com/docs/getting-started#adding-outstatic-to-a-nextjs-website. Only difference is that I skipped the typescript and used js instead. so my page.tsx is page.jsx instead with contents l like

import 'outstatic/outstatic.css';
import { Outstatic } from 'outstatic';
import { OstClient } from 'outstatic/client';

export default async function Page({ params }) {
    const ostData = await Outstatic();
    return <OstClient ostData={ostData} params={params} />;
}

• as for the assumption of CSS not being loaded. No requests made by the site result in errors. It seems everything is being loaded just fine. There's something weird going on there. For example. If I use "new collection" link on the /outstatic page to navigate to collections view ( outstatic/collections/new ), then the next page loads nice and pretty. Now if I use the "Outstatic" logo in the top-left corner to navigate back to '/outstatic', then the same view, which was broken before is now nice and pretty. If I reload the page, though, then it will break again. Same with other views. If I reload the page on `/outstatic/collections/new' then the page is "broken" again.

[avitorio]

Hey @OdifYltsaeb ,

Unfortunately I'm currently filled with work and won't have time to engage with helping you debug today. I'm also traveling tomorrow. I'll only be back online on Monday.

I suggest you look at our examples in the repository to see how things should be set up.

The source of truth for information on Outstatic is your GitHub repo, so you need to pull changes to see them locally.

I hope this helps.

[OdifYltsaeb]

@avitorio It's all good, man. I appreciate you trying to help at all. You've done something great and built a ready to use tool like this. I'ts insane effort. Believe me- I understand. I've not been able to do the same. So If you don't have time to deal with me it's fine. I already greatly appreciate your response.

I'm just trying to see if I can use outstatic as a simple tool for one basic project and to learn new tools. I'll go ahead and look at the codebase, but the codebase don't easily yield how you anticipate user flows. Hence the question about how you intend the work flows to be used. In any case - take care, man. Answer when you can and where you can. It's all good and much appreciated.

[OdifYltsaeb]

@avitorio, when you do get the chance, can you explain more about the workflow?

• Does it make sense to create a sub repository for the content or host the content along with the code of the website? But I guess that comes with all the other issues you get when you work with git submodules...
• Do I have to git pull after every change in the content for the content to be available through the db.load(... or is there something wrong with my setup if I have to? Because after saving the changes, I have to manually do a git pull for the db.load to yield the changed documents.

[avitorio]

Hey,
I don't think the submodules approach is a good one. You generally want your markdown files to be part of your project.

And yes, you need to git pull after each change.

[OdifYltsaeb]

Awesome. Thank you! Learning how the tool is supposed to work is very helpful for me. Think we can close this one.